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SECTION III 
GRAPHICS GENERATION SOFTWARE 
\ 
The graphics generation process is Structured on three levels of 
Software. A typical application will use routines from all three 
levels. These are the chip driver level, the table level and the 
object level. Figure 3-1 shows the Program flow, software 


Structure and its relationship with the outside world. 
Sea Chip Driver Level 


The graphics hardware consists of the VDP and 16K VRAM. 
The VDP has eight write-only control registers and one 
read-only status register. The chip driver level 
Software interfaces with the VDP registers and VRAM 
through the VDP. For detailed configuration of the 


registers, refer to the TMS 9928A VDP Data Manual. 


The chip driver level Software consists of six 


Subroutines: 
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READ _VRAM, WRITE_VRAM, READ REGISTER, WRITE_REGISTER, 
FILL _VRAM and MODE 1. The first five routines allow 
Programs to access the VDP registers and transfer 
information to and from VRAM blocks. The sixth routine, 
MODE_1, initializes the VDP into a standarg 


configuration. 
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3.1.1. READ _VRAM s 


Calling Sequence: 


LD HL, BUFFER 
LD —*+DE, ~SRCE 

LD ~—s-BC,_-COUNT 
CALL READ VRAM 


Description: 


READ_VRAM reads COUNT bytes from VRAM starting at SRCE 
and puts them in BUFFER, 


Parameters: 

BUFFER This is the starting address of a ry 
CRAM buffer which is to receive 
the data read from VRAM. 

SRCE VRAM starting address to be read 


from. 
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COUNT Number of bytes to be read from 
| 
VRAM. 


Legs 


Side Effects: 


- Destroys AF, BC, DE and HL. 


- Cancels any previously initiated VDP operations. 
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3.1.2 § WRITE_VRAM 


Calling Sequence: 


LD «HL, BUFFER 
LD ——DE, DEST 

LD ~—s BC, COUNT 
CALL WRITE_VRAM 


Description: 


WRITE_VRAM takes COUNT bytes from BUFFER and sends them 
through the VDP to VRAM. The starting address in VRAM 


for the write operation is given as DEST, 


Parameters: 


BUFFER This is the Starting address of a 


buffer where data to be sent to 


the VDP is located, 
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DEST This is the VRAM address where the 


data is to be ‘sent. 


COUNT This is the number of ores that 
are to be transferred to VRAM. 
Count should be either less than 
256 (100H) or even multiples of 
256. (Ref. ColecoVision Bulletin 
No. 0002). 


Side Effects: 


- Destroys AF, BC, DE and HL. 


- Cancels any Previously initiated VDP operations, 
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3.1.3 READ_REGISTER 7 


Calling Sequence: 


CALL READ REGISTER 


Description: 


READ_REGISTER reads and returns the contents of the VDP 
Status register in the accumulator. This value should 
be stored at VDP_STATUS_BYTE in CRAM. The information 
in this register can only be guaranteed valid during the 


vertical retrace time. 
Return value: 
Returns the contents of the VDP Status register which 


has the following form (see VDP manual for further 


details): 
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PRELIMINARY RELEASE CHAPTER 3 SOFTWARE 
Pe Pe EOS Entry Points 


AD0D816 EQU OFDSDH sP MEM_CNFGOF EGU OFC26H 3A 
BLK_STRTI_PIR EQU OFDDCH sD MEM_SwWITCH_PORT EQU OFC27H cA 
BLOCKS_REQ EQU OFEOCH ¢ MOO_LFILE_COUNT EQU OFDDSH 3 
BUF_END EQU GFEOAH sD MSNTOLSN EQU OFD4AH sp 
BUF_START EQU OFEO8H ¢ NET_LRESET_PORT EQU OFC28H H 
BYTES_REQ EQU OFEO2H ¢ NEW_HOLE_SIZE EQU OFE1AH ¢ 
BYTES_TO_6GQO EQU OFEO4H ¢ NEW_LHOLE_START EQU OFE16H : 
CALC_OFFSET EQU OFD32H ¢ NUM_COLUMNS EQU OFEAOH 3D 
CLEAR_RAM_SIZE EQU 00147H 3A NUM_LINES EQU OFESFH ¢ 
CLEAR_RAM_START EQU OFD60H ; JLOCHAR_ EQU OFE79H so 
COLGRTABLE EQU OFDE6CH 3; PATTRNGENTBL EQU OFD6AH 3 
CONTROLLER_O_PO EQU OFC2BH 3 PATTRNNAMETBL EQU OFD68H 3; 
CONTROLLER_1_PO EQU OFC2CH 3: Pca EQU GFECOH 34 
CURRENT_DEV EQU OFO6FH ¢ PERSONAL_DEBOUN EQU OFESAH H 
CURRENT_PCB EQU OFDT7OH 30 PLAY_IT EQU OFDS56H 3; 
CURSOR EQU OFEASH 3 POLLER EQU OFDSZEH ¢ 
CUR_BANK EQU OFD6EHM ¢ PORT_COLLECTICN EQU OFD11H H 
DCB_IMAGE EQU OFDBBH $¢$ PORT_TABLE EQU OFC2TH sa 
DECLSN EQU OFDS4H 5 PRINT_BUFFER EQU OFG76H 3 
OECMSN EGU GFD47H ¢ PTRN_NAME_TBL EQU OFEA3H 30 
OEFAULT_BT_DEY _EQU OFD6FH 3; PTR_TC_LST_OF_S EQu OFE6EH 3D 
OEVICE_ID EQU OFO72H ¢ PTR_TO_S_ON_O EQU OFET7OH ¢ 
OIR_BLOCK_NO EQU OFDD9H 5 PTR_TO_S_ON_1 EQU OFET72H 3; 
EFFECT_OVER EQU OFDSCH 3 PTR_TO_S_ON_2 EQU OFET746H 3; 
EOS_DAY EQU OFDE2H ¢ PTR_TO_S_ON_3 EQU OFET6H 3; 
ECS_MONTH EQU OFDEIH ¢ PUT_ASCII EQU OFDI7H 3P 
EOS_STACK EQU OFES8H 3; PUT_VRAM EQU OFD2CH 3; 
EOS_YEAR EQU OFDEOH ¢ PX_TO_LPTRN_POS EQuU OFD35H 3P 
FCB_BUFFER EQU OFOBAH 3D QUERY_BUFFER EQU OFDAGH 30D 
FCB_DATA_ADDR EQU OFOFFH 3; READ_REGISTER EQU OFD23H 3 
FCB_HEAD_ADDR EQU OFDFOH 3; “READ_VRAM EGU OFDIOH 3P 
FILENAME_CMPS EQU OFODBH 5 RETRY_COUNT EQU OFDDS6H 3; 
FILE_COUNT EQU OFDDSH 3; REVY_NUM EQU OFD60H 30 
FILELNAME_ADOR EQuU OFD73H ; SAVE_CTRiL ELU OFETBH $0 
FILE_NUMBR EQU OFDD7H ¢ SECTORS_TO_LINIT EQu OFDS86H ¢ 
FILL_VRAM EQU OFO26H 5P SECTOR_NO EQU OFD87H 3D 
FMGR_OIR_ENT EQU OFDE3H ¢ SCUNDPODRT EQU OFC2FH 3; 
FNUM EQU OFEOIH 3D SOUNDS EQU OFD59H 3; 
FOUND_AVAIL_ENT EQU OFDDBH 3: SOUND_INIT EQU OFDSOH ; 
GET_VRAM EQU OFO2ZFH ¢ SPIN_SWO_CT EQU OFESSH 3; 
INIT_TABLE EQU OFD29H ¢ SPIN_SwW1_CT EGU OFE59H gD 
INT_VCTR_TBL EQU OFBFFH sa SPRITEATTRTBL EQU OFD66H 30 
KEYBOARD _BUFFER EQU OFD75H ¢ SPRITEGENTBL EQU OFD66H ¢ 
LINEBUFFER_ EQU OFETEH 50 START_BLOCK EQU OFE12H 30 
LOAD_ASCII EQU OFD38H 3P STROBE_RESET_PD EQu OFC2EH 3A 
MEM_CNFGOO EQU OFC17H 3 STROBE_SET_PoRT EQU OFC2DH ¢ 
MEM_CWFGOI EQU OFCI8H 5A SWITCH MEM EQU OFD14H 3P 
MEM_CNFGO2 EQU OFCI9H ¢ SWITCH_TABLE EQU OFCI7H ga 
MEM_CMFGQ3 EQU OFCIAH ¢ TEMP_STACK EQU OFE6EH 3D 
MEM_CNFGO4 EQU OFC1BH 3A. TURN_OFF_SoOuND EQU OFD53H 3 
MEM_CNFGOS EQU OFCICH ¢ UPOATE_SPINNER EQuU OFDSin 3P 
MEM _CNFGO6 EQU OFCIDH ¢ UPPER_LEFT EGU OFEAIN 3; 
MEM_CNFGOT7 EQU OFCIEH sa USER_BUF EQU OFEOG6H 3; 
MEM_CNFGOS8 EQU OFCIFH sa USER_NAME EQU OFEIOH ¢ 
MEM_CNFGO9 EQU OFC20H 3 VDP_CTRL_PORT EQU OFC29H ¢ 
MEM_CNFGOA EQU OFC21H sa VDP_DATA_PORT EQU OFC2AH 3a 
MEM_CNFGOB EQU OFC22nH sa VDP_MCOE_wORD EQU OFD61HM 30 
MEM_CNFGOC EQU OFC23H cA VOP_STATUS_BYTE EQU OFD63H ¢ 
MEM_CNFGOD EQU OFC246H ¢ VECTOR_O8H ECU OFSFFH ¢ 
MEM_CNFGOE EQU OFC25H ga VECTOR_10n EQU OFCO2H sa 
VECTOR_18Hn EQU OFCOSH ¢ 
VECTOR_20n EQU OFCOBH sa 


VECTOR_28n EQU OFCOSH sa 
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| Interrupt | Fifth Sprite | Coincidence | Fifth Sprite No] 
Figure 3-2 


= een eee eer 


VDP Status Register 


Side Effects: 


This routine has no effect at all in the processor 
memory or register space. However, a status read has a 


Significant side effect to the VDP. 


It acts as an interrupt acknowledge operation, i.e., it 


clears the interrupt flag and enables further generation 


' of interrupts. 


Thise side effect must be treated with care for two 
reasons. First of all, as is pointed out in the VDP 
manual, segneheonaus reads may cause the interrupt flag 
in the status register to be reset before it is 
detected; this may cause problems in Systems that expect 


to perform synchronization using the interrupt flag. 
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The second reason concerns interrupts which halt the 
execution of routines while they are accessing VRAM. In 
order to re-enable interrupts, a service routine must 
read the status register. However, to prevent the NMI 
from re-interrupting the service routine, the — 
should avoid reading the status register until all of 
its work is done. A defer interrupt routine, DEF_INT, 
has been developed to assist the user ‘5 handling this 
Situation. Refer to ColecoVision Bulletin No. 0010 for 


additional information. 
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Sled WRITE REGISTER 


Calling Sequence: ‘ 
LD B, REGISTER 
LD C, VALUE 


CALL WRITE REGISTER 


Description: 


WRITE_REGISTER takes VALUE and writes it to the VDP 


register numbered REGISTER, 


WRITE REGISTER also maintains two bytes in CRAM Starting 
at address VDP_MODE_WORD. The first is intended to 
Guplicate the current contents of VDP Register 0, and 
the second to duplicate Register 1, When writing to a 
register using WRITE REGISTER, the appropriate half of 
VDP_MODE_WORD is updated. 
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Parameters: 
REGISTER This is the VDP register number 
(0 = 7) to be written. 
VALUE This is the value to be written to 
REGISTER, 


3 eres eee 


Side Effects: 


- Destroys the AF register pair. 
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3.1.5 FILL_VRAM 


a 


Inc. 1982 


Calling Sequence: 


LD 
LD 
LD 
CALL 


HL, ADDRESS 
DE, COUNT 
A, VALUE 
FILL VRAM 


Description: 


FILL_VRAM writes COUNT copies of VALUE to VRAM st 


at ADDRESS, 


Parameters: 


ADDRESS 


COUNT 


VRAM address to Start fill 


Operation. 


Number of bytes to £i13.. 


arting 
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VALUE 8=-bit value to fill with. 


Side Effects: 


- Destroys AF and DE. 


- Cancels all previously initiated VRAM operations. 
Calls to other OS routines: 


- READ REGISTER (Ref. Sec. 3eda3) 


o os Dm mH mR & © oo 


oun ef BSwe Ss Set ewe ee ew ym 
aun we nber CO MN Aha DHE S 


f COLECOVISION PROGRAMMERS' MANUAL 


Rev. 5 


s ©Coleco Industries, Inc. 1982 


f CONFIDENTIAL DOCUMENT = DO NOT COPY 3-15 


a 


3.1.6  MODE_1 


Calling Sequence: 


CALL MODE_1 


Description: 


MODE 1 sets the VDP to graphics mode 1 and sprite size 


0. It also uses the INIT_TABLE routine to define the 


VRAM table addresses as follows: 


- Sprite Generator Table - 3800H 
- Patter Color Table - 2000H 
- Sprite Attribute Table - 1BO0H 
- Pattern Name Table - 1800H 
- Pattern Generator Table - OOOOH 


When MODE_1 returns, the screen is blanked and the 


backdrop plane color is set to black. 
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! 
Side Effects: 


- Destroys AF, BC and HL. 


Calls to other OS routines: 


- WRITE REGISTER 
- INIT_TABLE 


3-16 
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3.2 Table Level ? 


The VDP requires various table areas within VRAM to 
operate. These tables are interrelated, sagen 
controlling its own aspect of the graphics generation 
process. The table level software provides routines 
which will read or write VRAM with respect to these 
table areas. The routines also provide the capability 
of reading and writing entire tables entries or sections 
of these entries up to and including the whole table. 
This level also has Special functions which were found 
helpful, 

The major difference between the table level and the 
chip driver level is that the applications programmer is 
no longer required to manipulate VRAM addresses on the 
table level. Instead, each of the VRAM tables is 


assigned a number or table code as listed in Table 3-1. 
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Scenes 


Table Name 


Sprite attribute table 
Sprite generator table 
Pattern name table 
Pattern generator table 
Pattern color table 


Table 3-1 
VRAM Table Code 


When an applications program needs to operate on a 
table, only a table code needs to be passed to the 
applicable table Processing the routine. 
Furthermore, in graphics mode 1 and graphics mode By 
which are Supported by the oS graphics software, the 


tables have more or less fixed Shapes. The entry 


numbers and bytes per entry for each of the five tables, 


@s well as their boundaries, is Eiven in Table 3-2, 


o on nM wT Bw Ww PD ww 


bp wt RD DD WD ppD DS wo ee we a en ee 
A wk © He OCH HUY] REBELS 


COLECOVISION PROGRAMMERS' MANUAL 


Rev. 5 
©Coleco Industries, Inc. 1982 
CONFIDENTIAL DOCUMENT = DO NOT COPY 3-19 


BYTES/ 
ENTRIES | ENTRY 
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a ee ee ee ee ee | 
Table 3-2 


Table Entries and Boundaries 


The table management software takes advantage of this 
regularity by letting application programs address table 
entries as integral entities. Let us take, for example, 
the task of getting the 14th sprite attribute = from 
VRAM. In terms of the chip driver software, the task 


appears as follows: 


Get sprite attribute table address, 


Calculate offset into table (14 #® table row 


length). 


Add offset to address, 


- Read one table entry (4 bytes) from VRAM at 


off set + attribute table address. 
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On the other hand, when using the table level software, 


the task is now reduced to the folfowing: 


- Give offset into table (14). 


Give table code. 


Give item count (1): 


Call GET_VRAM (places the desired bytes at a 


user-defined area). 


In a video program that requires accessing the sprite 
attribute table frequently (for example, an action- 
Oriented game), the table level method constitutes a 
Significant Savings in cartridge code. 

Software in the table level may be further subdivided 


into three groups of routines as follows: 


- Table Managers 
- Table-oriented Graphics Routines 


- Sprite Reordering Software 
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1] 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
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Sebel Table Managers 


There are three routines in this group: INIT TABLE, 
GET_VRAM and PUT_VRAM. As the names imply, they deal 
with table initialization, getting data from tables ang 


Placing data into tables, respectively. 


Table initialization is a very simple operation which 
involves assigning a base address to a table. The base 
addresses are "Saved" for later use by GET_VRAM and 
PUT_VRAM for address calculations and remain fixed until 
they are reinitialized. GET_VRAM and PUT_VRAM both take 
a table code, an entry number, as well as an element 
count and @ buffer address in CRAM as parameters — 
they perform their respective transfers of information 


between CRAM and VRAM. 


o ont DM HT mR Ww 20 wo 


po Pm SP YP pp DY ew we — wo elo = 
nh a oe a 8 coO MON DHRBDHRH eS 


COLECOVISION PROGRAMMERS' MANUAL 


; Rev. 5 
y ©Coleco Industries, Inc. 1982 
fh CONFIDENTIAL DOCUMENT — DO NOT COPY 3-22 
e 
Seated INIT_TABLE 


Calling Sequence: 


LD A, TABLE CODE 
LD «HL, ADDRESS 
CALL INIT TABLE 


Description: 


INIT_TABLE takes a table code and a VRAM address at 
which that table is to reside, and initializes the VDP 
base address register for the given table. It also 
Stores the unconverted form of the address in an array 
called VRAM_ADDR_TABLE for later use in address 
arithmetic. This address is stored at 


VRAM_ADDR_TABLE [TABLE_ CODE]. 


INIT_TABLE makes use of the current @raphics mode in 


determining the actual value written to the base address 


register in some cases. It determines the graphics mode 
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by looking at the VDP_MODE WORD. Thus, it is imperative 


that the graphics mode be set up usimg WRITE_ REGISTER 


before INIT TABLE. 


Parameters: 


TABLE_CODE 


ADDRESS 


Side Effects: 


Number of the table to be 
initialized. TABLE_CODE must be 
One of the legal table codes 


defined in Table 3-13, 


Intended VRAM address of table, 
Each table has its own boundary 
defined by the table base address 
in the VDP conemen register. The 
user should refer to Table 3-2 for 


the proper table boundary. 


- Destroys AF, BC, HL, IX and IY. 
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Calls to other OS routines: 


- REG_WRITE 


3-24 
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3.2.1.2 GET_VRAM 


SSS Sy Saas 


Calling Sequence: 


LD 
LD 
LD 
LD 
CALL 


A, TABLE CODE 
DE, START_INDEX 
HL, DATA 
IY, COUNT 
GET_VRAM 


Description: 


3-25 


GET_VRAM reads into the CRAM buffer DATA, COUNT entries 


from the table specified by TABLE CODE, which starts at 


the table entry number START_INDEX. 


GET_VRAM uses the VDP_MODE_WORD and VRAM_ADDR_TABLE to 


calculate VRAM addresses and byte counts. 


It is 


imperative, before calling GET_VRAM, that the graphics 


mode be initialized using WRITE_REGISTER, and that the 


table being accessed be initialized using INIT_TABLE. 
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Parameters: 
. ] 
TABLE_CODE VRAM table code (Table 3-1) to be 


START_INDEX 


read. 


START_INDEX is a two=-byte number 
that indicates the Starting entry 


of the table. 


The range of START_INDEX is table 
dependent. However, no boundary 
checking is done; therefore, if an 
index is given that is outside the 
range of the table, but still a 
legal VRAM address, the specified 
number of "entries" will be 
extracted from that location in 


VRAM. 


Both the pattern generator and the 
color tables in graphics mode 2 


are 768 entries long and they are 
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DATA 


COUNT 


Segmented into three sections 
corresponding “to the three 
sections of the display. When 
addressing these tables, ‘co high 
order byte (D) of the two-byte 
START_INDEX value is a "segment 
specifier" (0 <= D <= 2), while 
the low order byte (E) specifies 
the index of the entry in that 


Segment. 


In the case of the Sprite 

generator table, please note that 
COUNT refers to 8-byte shape for 
entries whether one is using size 


O or size 1 sprites. 


Starting address of a CRAM data 


buffer to receive data from VRAM. 


Number of entries to be read from 


the VRAM table, 
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The restrictions on COUNT are 
again table depeniont, In other 
words, it should always be the 
case that START_INDEX + COUNT <= 
Table Size, 


Side Effects: 

- Destroys AF, BC, DE, HL, IX and IY. 

- This routine uses the local Storage area SAVED COUNT 
and is therefore not re-entrant. 


Calls to other OS routines: 


- READ_VRAM 
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e 
3.2.1.3 PUT_VRAM 
Calling Sequence: \ 


LD 
LD 
LD 
LD 
CALL 


A, TABLE_CODE 
DE, START_INDEX 
HL, DATA 

IY, COUNT 
PUT_VRAM 


Description: 


PUT_VRAM w ites from the buffer DATA, COUNT entries to 


the table specified by TABLE CODE, which starts at the 


table entry number START_INDEX. 


PUT_VRAM uses the VDP_MODE_WORD and VRAM_ADDR_TABLE to 


Calculate VRAM address and byte counts. It is 


imperative that the graphics mode be set up using 


WRITE_ REGISTER and the table being accessed be ini- 


tialized using INIT_TABLE before PUT_VRAM is called. 
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The table level of Braphics software contains a Sprite 
reordering feature where the major effect is in the 
operation of PUT_VRAM. When the MUX_SPRITES flag is set 
to TRUE (1), PUT_VRAM writes Sprite entries to e CRAM 
copy of the sprite attribute table instead of writing 
them to VRAM. It locates this table through a pointer 
in low cartridge ROM called LOCAL_SPR_TBL. The sprite 


entries will then be re-ordered before being written to 


VRAM. 

Parameters: 

TABLE CODE VRAM table code (Refer to Table 
3-1) to be written. 


START_INDEX START_INDEX is a two-byte number 
, which indicates the starting 
entry number of the table. For 
other considerations, refer to 
the START INDEX parameter of 
GET_VRAM in Section 3.2.1.2. 


o ont DH & Ww DW oe 


Anne | we BM SG FE ony aun apes 


) COLECOVISION PROGRAMMERS! MANUAL 


f Rev. 5 
j ©Coleco Industries, Inc. 1982 
CONFIDENTIAL DOCUMENT ~ DO NOT COPY 3-31 
DATA Starting address of a data buffer 


COUNT 


Side Effects: 


where data to ‘be written to VRAM 
resides, 

\ 
Number of entries to be put to the 


VRAM table. 


The restrictions on COUNT are 
again table dependent. In other 
words, it should always be the 
case that START_INDEX + COUNT <= 
Table Size. 


- Destroys AF, BC, DE, HL, IX and IY. 


- Uses local storage locations, SAVE_TEMP and 


SAVED_COUNT, 


Calls to other OS routines: 


- WRITE_VRAM 
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Table-Oriented Graphics Routines 


A number of routines are included in the table level 
graphics software that perform useful operations on 
generators. Each of these takes a table code, a source 
index from that table, a destination index in the same 
table, and the number of entries to be processed. The 
routines work in read-modify-write mode, that is, they 
Pull the generators out of the table one at a time, 
Process them and put them back. They use a CRAM buffer 
for their scratch area, This buffer is allocated by the 
applications programmer and accessable only through the 


Pointer at WORK BUFFER in cartridge ROM. 


With one exception, the routines in this package always 
Process generators one at a time, and write them to the 
destination block in the Same order in which they are 
extracted from the source block. This has important 


implications for their use with size 1 sprites. 


When the sprite size is 1, the hardware accesses four 


generators at the index found in a Sprite's attribute 
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table entry and displays them so that they appear on the 


Screen as Shown in Figure 3-3. 


Sprite Screen Location # 


third \ 
generator 


first 
generator 


S 


fourth 
generator 


second 
generator 


Figure 3-3 
Sprite Size 1 Orientation 


Thus, OS routines Operating on the individual generators 
for a size 1 sprite will not be sufficient to orient the 
entire object. The four generators that make up the 
Sprite will have to be permuted as well. The 
applications program will have to include a small 
routine that performs the required permutation in tandem 


with the OS call. 


The following operations are available in the table- 


Oriented graphics package: 
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SSSI eee 


Reflection about the vertical axis 


Reflection about the horizontal axis 


90-degree rotation 


Enlargement by a factor of two 


3=34 
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! 


3.2.2.1 REFLECT_VERTICAL 


SSS eeeageeanaars 


Calling Sequence: 


LD A, TABLE CODE 

LD DE, SOURCE 

LD HL, DESTINATION 
LD BC, COUNT 

CALL REFLECT VERTICAL 


Description: 


REFLECT_VERTICAL takes each generator in a block of 
COUNT generators following SOURCE in the table indicated 
by TABLE CODE and modifies it in such a way that the new 
generator thus created will appear to be a reflection 
about the vertical screen axis of the old. The created 
generators are put back into a block of COUNT generators 


following DESTINATION in the same table. 


The user must provide the permutation for size 1 sprite 


generators as diagrammed in Figure 3-4 below: 
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=---> first generator 
---4 ---> 


o--- third generator <-{<- 
fourth generator < 


ure 3-4 
REFLECT - VERTICAT. Sipe 1 Sprite Permutation 


af TABLE_CODE is 3 (indicating the pattern generator 
table) and graphics mode 2 is used, REFLECT VERTICAL 
also copies the color table entries for each generator 
© processes. Thus, when it is complete, the two-color 
table blocks indexed by SOURCE and DESTINATION will be 
identical. This means that the color scheme for the 
reflected generators will be the same as that for the 


Originals. 
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Parameters: 
@ 
TABLE CODE VRAM table code (Ref. Table 3-1) 


SOURCE 


to be operated upon, \ 


SOURCE is the two-byte index of 
the first entry in the Specified 


table to be operated on, 


For table operations of Sprite 
generator or pattern generator in 
Graphics mode 1, SOURCE should be 
in the range 0 <= SOURCE <= 2O5% 
For pattern generators in mode 2, 
it should be in the range 0 <= 
SOURCE <= 767. In either case, if 
@ value of SOURCE Supplied is 
Outside the table's range but 
still is a legal VRAM address, the 
Specified number of "entries" will 
be read and modified from the VRAM 


location (table location) + 8 # 
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Se oe 


DESTINATION (HL) 


COUNT (BC) 


SOURCE. For the proper table 
e 
entries and table boundary, refer 
to Table 3-2. 
\ 
Sprite size has no effect on the 


range of SOURCE. 


DESTINATION indexes the place where 
REFLECT_VERTICAL will start putting 
generators back into VRAM after 


modifying them. 


The same restrictions apply to the 
value of DESTINATION as to the value of 
SOURCE, They are both intended to be 


indices into the same generator table. 


A two-bytes count of the number of 
entries to be processed sequentially 


after SOURCE. 
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The legal value for COUNT is dependent 
on the size of the table being operated 
On and the values of SOURCE and 
DESTINATION. In general, “pun Gt the 


following statements should be true: 


COUNT + SOURCE <= (table Size) 
COUNT + DESTINATION <= (table size) 


Side Effects: 
- Destroys AF, AF’, BC, DE, DE', HL, HL', IX and IY. 
- Uses the first 16 bytes of the data area pointed to by 
WORK_BUFFER, 


Calls to other OS routines: 


- GET_VRAM 
- PUT_VRAM 
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3a2ee.2 REFLECT _HORIZONTAL 


Calling Sequence: 


LD 
LD 
LD 
LD 
CALL 


A, TABLE CODE 
DE, SOURCE 

HL, DESTINATION 
BC, COUNT 
REFLECT_HORIZONTAL 


Description: 


REFLECT_HORIZONTAL takes each generator in a block of 


COUNT generators following SOURCE in the table indicated 


by TABLE CODE and modifies it in Such a way that the new 


generator created will appear to be a reflection about 


the horizontal Screen axis of the old. The created 


generators are placed back into a block of COUNT 


generators following DESTINATION in the same table. 


The user has to provide the permutation for size l 


Sprite generators as diagrammed in Figure 3-5. 
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Block indicated by sprite name: 


Figure 3-5 
REFLECT_HORIZONTAL Size 1 Sprite Permutation 


If TABLE CODE is 3 (indicating the pattern generator 
table) and the graphics mode is @, REFLECT_HORIZONTAL 
also performs the identical reflection on the 
corresponding color table entry for each generator it 
Processes. This means that the reflected generators 
Will be colored in a way that is consistent with their 


unreflected counterparts. When in mode 1, the color 


table is untouched. 
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Parameters: 

e 
TABLE _CODE VRAM table code (Ref. Table 3-1) 
to be operated upon. \ 

SOURCE SOURCE is the two-byte index of 


the first entry in the specified 


table to be operated on. 


For table operations on sprite 
generator or pattern generator in 
graphics mode 1, SOURCE should be 
in the range 0 <= SOURCE c= 25D. 
For pattern generators in mode ey 
it should be in the range 0 <= 
SOURCE <= 767. In either case, if 
&@ value of SOURCE is supplied and 
is outside the table's range but 
Still a legal VRAM address, the 
Specified number of "entries" will 
be read and modified from the VRAM 
location (table location) + 8 # 
SOURCE. For the proper table 
entries and table boundary, refer 


to Table 3-2, 
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DESTINATION 


COUNT 


Sprite size has no effect on the 


range of SOURCE. 


DESTINATION indexes the place 
where REFLECT_VERTICAL will start 
putting generators back into VRAM 


after modification. 


The same restrictions apply to the 
value of DESTINATION as to the 
value of SOURCE. They are both 
intended to be indices into the 


Same generator table, 


A two-byte count of the number of 
entries to be processed 


Sequentially after SOURCE, 


A legal value for count depends on 
the size of the table being 
Operated on and the values of 


SOURCE and DESTINATION. In 
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general, both of the following 
e 


Statements should be true: 
COUNT + SOURCE <= (table ¢ize) 
COUNT + DESTINATION <= (table 
size) 

Side Effects: 

- Destroys AF, AF', BC, DE, DE’, HL, HL’, IX and Iy. 

- Uses the first 16 bytes of the data area pointed to by 

WORK_BUFFER. 


Calls to other OS routines: 


- GET_VRAM 
- PUT_VRAM 
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Seeates ROTATE _90 
Calling Sequence: 


LD A, TABLE _CODE 
LD DE, SOURCE 

LD HL, DESTINATION 
LD _—-&BC, COUNT 

CALL ROTATE 90 


Description: 


ROTATE _90 takes each generator in a block of COUNT 
generators following SOURCE in the table indicated by 
TABLE CODE and modifies it in such a way that the new 
generator thus created will appear to be a 90-degree 
Clockwise rotation of the old. The created generators 
are put back into a block of COUNT generators following 


DESTINATION in the same table. 


The user must Provide the permutation for size l sprite 


generators as diagrammed in Figure 3-6 below: 
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Block indicated b Sprite name: 


| 


Siena third generator ] <---- 


Figure 3-6 
ROTATE 90 Size 1 Sprite Permutation 


This routine should be used with great care when applied 
to pattern generators in mode 2. In this mode, the VDP 
allows arbitrary color combinations along vertical lines 
while it is still limited to two colors along a given 
8-pixel horizontal line. The problem is that if the 
user attempts to rotate a figure that has more than two 
colors on a vertical line, ROTATE 90 will exhibit color 
Problems after rotation. There is no Way around this 
Problem except to keep any generators that are intended 


for rotation simple. If the TABLE CODE is 3 (pattern 
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I generator table) and the mode is 2, ROTATE 90 will copy 
4 e 
= the corresponding color table entries indexed by SOURCE 
> to the block indexed by DESTINATION, 
4 | 
\ 
5 | | 
6 Parameters: : 
7 | 
{ 
8 TABLE CODE VRAM table code (Ref. Table 3-1) 
| 
9 to be operated upon. 
10 
n SOURCE SOURCE is the two-byte index of 
12 the first entry in the Specified 
: table to be operated on. 
13 | 
14 f 
15 | For table operations of sprite 
16 | generator or pattern generator in 
v7 | §raphics mode 1, SOURCE Should be 
1s | in the range 0 <= SOURCE <= 255. 
‘is For pattern generators in mode 2. 
20 it should be in the range 0 <= 
zy SOURCE <= 767. In either case, if 
29 &@ value of SOURCE jis Supplied and 
23 is outside the table's range but 
24 
25 
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8till is a legal VRAM address, the 
ca] 

Specified number of "entries" will 

be read and modified from the VRAM 


location (table location), + 8 # 


SOURCE. For the proper table 


entries and table boundary, refer 


to Table 3-2. 


Sprite size has no effect on the 


range of SOURCE. 


DESTINATION DESTINATION indexes the place 
where REFLECT VERTICAL will start 
putting generators back into VRAM 


after modifying them. 


The same restrictions apply to the 
value of DESTINATION as to the 
value of SOURCE. They are both 
intended to be indices into the 


Same generator table, 
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COUNT . A two-byte count of the number of 


Ses 


@ 
entries to be processed 


Sequentially after SOURCE, 

\ 
The legal value for count is 
dependent on the size of the table 
being operated on and the values 
of SOURCE and DESTINATION. In 
general, both of the following 


Statements should be true: 


COUNT + SOURCE <= (table size) 
COUNT + DESTINATION <= (table 


Size) 
Side Effects: 
- Destroys AF, AF", BC, DE, DE’, HL, HL' IX and IY. 


- Uses the first 16 bytes of the data area pointed to by 
WORK_BUFFER, 
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Calls to other OS routines: e 
- GET_VRAM 
- PUT_VRAM ‘ 
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3.2.2.4 ENLARGE 


Calling Sequence: \ 


LD A, TABLE CODE 
LD _—~DE, ~SOURCE 

LD HL, DESTINATION 
LD  —- BC, COUNT 

CALL ENLARGE 


Description: 


ENLARGE takes each generator in a block of COUNT 
generators following SOURCE in the table indicated by 
TABLE_CODE and from it creates four generators as shown 


below in Figure 3-7. 
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ee 


first third 
generator generator 


second fourth 
generator generator 


Figure 3-7 
ENLARGE Generators Layout 


The enlarged object will appear to be a double-sized 
version of the original. The created generators are put 
back into a block of 4 * COUNT generators following 


DESTINATION in the Same table. 


Note that since the ordering of the- expanded generators 


is the same as that for the four generators needed to 


Produce a size 1 Sprite, ENLARGE lends itself well to 


use with Sprites as long as the Programmer is willing to 
dedicate four times as many Sprites to the expanded 


object as to the orginal. 


If TABLE CODE is 3 (indicating the pattern generator 


table) and the graphics mode is 2, ENLARGE makes four 
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copies of the color table entry for each source 
generator and places them in the color table so that 
they correspond to the four destination generators, 

This should mean that the color scheme for the enlarged 
object will be the same as that of the original. If the 


mode is 1, the color table is untouched. 


Parameters: 

TABLE CODE VRAM table code (Ref. Table 3-1) 
to be operated upon. 

SOURCE SOURCE is the two=-byte index of 


the first entry in the Specified 


table to be operated on. 


For table operations on @ Sprite 
generator or a pattern generator 
in graphics mode 1, SOURCE should 
be in the range 0 <= SOURCE <= 
255. For pattern generators in 


mode 2, it should be in the range 
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El 


O <= SOURCE <= 767. In either 
case, if a velae of SOURCE is 
Supplied and is outside the 
table's range but still a, legal 
VRAM address, the Specified number 
of "entries" will be read and 
modified from the VRAM location 
(table location) + 8 # SOURCE. 

For the proper table entries and 
table boundary, refer to Table 


3-2. 


Sprite size has no effect on the 


range of SOURCE. 


DESTINATION DESTINATION indexes the place 
where ENLARGE will start placing 
generators back into VRAM after 


modifying them. 


The same restrictions apply to the 


Value of DESTINATION as to the 
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value of SOURCE. They are both 
intended to be indices into the 
Same generator table. 
\ 
COUNT A two-byte count of the number of 
entries to be processed 


Sequentially after SOURCE. 


The most important factor limiting 
the size of COUNT in the case of 
the ENLARGE routine is that 
ENLARGE actually produces four 
generators for every generator 


that it reads. 


The legal value for count depends 
on the size of the table being 
operated on and the values of 
SOURCE and DESTINATION. Both of 
the following statements should be 


true: 
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COUNT + SOURCE <= (table size) 
DESTINATION + 4 * COUNT) <= 


(table size) 
Side Effects: 
- Destroys AF, AF', BC, DE, DE', HL, HL', IX and IY. 
- Uses the first 4o bytes of the data area pointed to by 
WORK_BUFFER, 


Calls to other OS routines: 


- GET_VRAM 
- PUT_VRAM 
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3623 


Sprite Reordering Software 


Probably the most Significant hardware limitatibn of the 
VDP is the so-called "fifth sprite problem." This 
Problem arises when more than four sprites occur ona 
Single horizontal scan line. Because the chip only has 
four registers for dealing with the lower order Sprites, 
the sprites with the higher sprite attribute indices 
Cannot be generated on that scan line and therefore 


disappear. 


One solution to this Problem is to use a peorderine 
Scheme on the offending sprites which involves swapping 
the priorities of the Sprite that is being blanked out 
with that of one of the higher order sprites in the 
Broup on successive video fields. The result is that 
while the sprites that are being reordered tend to 
flicker in the area of Overlap, they are still quite 
visible. The degree of flicker depends on many factors 
including the color of the Sprites in question and the 


background color and complexity. 
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The OS supports this solution by allowing the 
application to adjust the order of Sprite attribute 
entries with minimum effort. 

Two tables are used in implementing the sprite ’ 
reordering feature. The first of these is simply a 
local CRAM version of the VRAM Sprite attribute table. 
It must be allocated by the application program and made 
accessible to the OS by placing a pointer to it at the 
Predetermined cartridge ROM location LOCAL_SPR_TBL. 

This local sprite attribute table need Only contain the 
active sprite entries needed by the application and 
therefore may be shorter than the 128 bytes required for 
the VRAM version. The other table is called the sprite 
order table. It is also allocated be the application 
Program through a pointer, SPRITE ORDER, located in 
cartridge ROM. The sprite order table should contain 
One byte for each entry in the local Sprite attribute 
table, and the bytes should take on values in the range 


0 <= b <= 31. 


When the flag MUX_SPRITES is false (0), PUT_VRAM writes 


Sprite attribute entries directly to VRAM. However, 
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when this flag becomes true (1), they are written 


e 
instead to the local Sprite attribute table. Then, a 


routine called WR_SPR_NM_TBL will map the local Sprite 
attribute entries to VRAM according to the Sprite order 


table. 


An example of the relationship between the three tables 


may be illustrated as follows: 
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e Sprite 

Local Sprite Sprite Order Attribute 
Table (CRAM) Table (CRAM) Table (VRAM) 
| entry 0 | ---------. > 0 | --------- >| entry 0 | 
| entry 1 | ---------- > 3 | ----- | entty 1 | 
| entry 2 | ---------- > 17 | 4 entry 2 | 

: : --> entry 17 | 


Figure 


3-8 


Sprite Reordering Table Mapping 


The advantage of this method lies in the fact that it 


takes a lot less work to 


order table than it does 


reorder the bytes in the sprite 


to move around the entries in 


the VRAM or CRAM sprite attribute tables. 
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Seessek INIT_SPR_ORDER 


Calling Sequence: 


LD A, SPRITE_COUNT 
CALL INIT_SPR_ORDER 


Description: 


INIT_SPR_ORDER looks at the pointer SPRITE_ORDER in low 
cartridge ROM which should contain the address of a free 
area SPRITE COUNT bytes long in CRAM. It sets this area 


up 4S @ Sprite order table by initializing it with 


zero through SPRITE_COUNT - 1, 


Parameters: 


SPRITE COUNT The length of the Sprite order 
table, which whould be the same 
as the intended number of entries 


in the local sprite attribute 


table. 
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This number must &lways be 


range 1 <= SPRAITE_COUNT <= 


Side Effects: 


- Destroys AF, BC, and HL. ° 


in the 
Sas 
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3.2.3.2 WR_SPR_NM_TBL 


Calling Sequence: 


LD =A, _-COUNT 
CALL WR_SPR_NM_TBL 


Description: 


WR_SPR_NM_TBL writes COUNT entries from the local sprite 
attribute table, which it accesses through the pointer 
LOCAL_SPR_TBL in low cartridge ROM, to the VRAM sprite 
attribute table. The transfer is mapped through the 
Sprite order table which it accesses through the pointer 


SPRITE_ORDER in low cartridge ROM. 


Parameters: 


COUNT This is the number of Sprite 


attribute entries to be written to 


VRAM. 
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y 


; 
COUNT should not be larger than 
the initialized length of the 


Sprite order table, 


Side Effects: 


. 


- Destroys AF, BC, DE, HL, IX and Iy, 


| - Cancels any previously established Vpp operations, 


a ee 


( 


o ont nw m& & 00 po 


pw PY PD wD DY we mw wD ~- bt eles rr) 
a ee a a Ss & 


COLECOVISION PROGRAMMERS' MANUAL 


3.3.1 


Rev. 
p ©Coleco Industries, Inc. 1982 
CONFIDENTIAL DOCUMENT — DO NOT COPY 3-65 
@ 
3.3 Object Level 


The object level software constitutes the top level of 
the graphics generation Software, which appears to the 
user @s& a collection of Berean objects with well-defined 
Shape, color scheme, and location at any given moment. 
The software Supports four distinct object types, each 
of which has its own capabilities and limitations. Once 
objects are defined, however, the rules for manipulating 
them are fairly type-independent. In fact, only one 
routine (PUTOBJ),is used to display objects of all 


types. 


Brief descriptions are given in the following sections 
in regard to Object types, object data structures and 
two user-accessible routines (ACTIVATE, PUTOBJ). For 


further information, refer to Appendix B, 
Object Types 


There are four different types of objects defined by the 


OS. A brief description for each type is given below. 


o on Dn mH m & 0 


Dm mM ND PD we ae ke a ee 
pe »o © o & or Hae DBH & o 


COLECOVISION PROGRAMMERS' MANUAL 


| Rev. 5 
©Coleco Industries, Ine. 1982 
CONFIDENTIAL DOCUMENT — DO NOT Copy 3-66 


3.3.1.2 


3% Se ked 


Semi-mobile objects are rectangular arrays of pattern 

blocks which are always aligned on pattern boundaries, 
\ 

Their animation capability is limited. In most cases 


they are used to set up background pattern graphics, 
Mobile 


The size of a mobile object is fixed in two-by-two 
pattern blocks, They belong to the pattern plane but 
can be moved from pixel to pixel in X,Y directions like 
@ sprite superimposed on the background. However, the 
Speed of mobile objects are too slow when compared to 


the sprites, 
Sprite 


Sprite Objects are composed of an individual Sprite. 
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3.3.1.4 Complex 


3.362 


Ck ee 


Complex objects are collections of other "component" 


objects which may be of any type including other complex 


objects. 


Object Data Structure 


Fach of the above mentioned objects has its definition 
in cartridge Rom, This high-level definition links 

together several different data areas which Specify all 
aspects of an object. The data Structure is described 


in detail in Appendix B, 


Graphics Data Area 


This data area is located in Cartridge ROM. Pattern and 
color generators for Semi-mobile, mobile and sprite 
objects and Paris data for all objects are located in 
the graphics data area. The data structure within each 
graphics area depends on the type of object with which 
it is associated, if, however, two or more objects of 


the same type are graphically identical, they may share 
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SaSe2e2 


32 302s3 


the same graphics area, This will reduce the amount of 
@ 


graphics data that needs to be Stored in cartridge Rom, 
Status Area \ 


Each object will have its own Status area in CRAM. The 
game program uses this area to manipulate the object. 

It does this by altering the location within status 
which determines which frame is to be displayed as well 
as the locations which define the position of the object 
On the display. The graphics routine, PUTOBJ, when 
called, will access the object's status area and place 


the object accordingly. 
OLD_SCREEN 


Mobile and Semi-mobile objects appear in the pattern 
Plane. They are displayed by altering some of the names 
in the pattern name table. The Original names represent 
& background which is "underneath" the object. When the 
object moves or is removed from the pattern plane, the 


Original names must be restored to the name table. 
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Before placing a semi-mobile or mobile object on the 
display, PUTOBJ will restore any previously Saved names 
and also save the names which constitute the background 
underneath the new location of the object. Sprite anda 
complex objects do not need OLD SCREEN seaee. 


a 


fo a ACTIVATE 
Calling Sequence: 


LD HL, OBJ_DEF 
SCF 
CALL ACTIVATE 


or 
- LD HL, OBJ_DEF 


OR A 
CALL ACTIVATE 
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Description: 

@ 
The primary purpose of this routine is to move the pat- 
tern and color generators from the graphics data area 
into the pattern and color generator tables in VRAM. 
Each object must be "activated" before it can be 
displayed. ACTIVATE @lso initializes the first byte in 
an object's OLD_SCREEN data area with the value 80H. 
PUTOBJ tests this location before restoring the 
background names to the name table. If the value 80H is 
found, it is an indication that there are no background 


names to restore, 


Parameters: 
OBJ_DEF High level definition of an 
| object. See Appendix B for 
further details, 
SCF Carry flag should be set if user 


wishes to load the generators spe- 


cified for this object. 
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OR A Carry flag should be reset if user 


Se Sah 


knows that the generators are 


already in VRAM,. 


PUTOBJ 


Calling Sequence: 


LD IX, OBJ_DEF 
LD —siB,_-_BKGND_SELECT 
CALL PUTOBJ 


Description: 


PUTOBJ is called when an object's frame or its 
location on the display is to be changed. The routine 
tests the type of object and then branches to one of 
Several subroutines designed to handle that particular 
object type. These routines are not accessible to the 


user. Their functions are as follows: 
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PUT_SEMI 


Semi-mobile objects are placed on the display by 
writing the generator names specified by ene of the 
object's frames into the pattern name table in 
VRAM. The wuteoen and color generators which are 
needed to create the frame must already be in their 


respective generator tables. 


PUT_MOBILE 


Mobile objects are displayed by producing a new set 
of pattern and color generators which depict the 
frame to be displayed on the background. These new 


generators are then moved to the locations in the 


VRAM pattern and color generator tables which are 
reserved for the object; the names of the new 


generators are then written into the pattern name ta 


PUT_SPRITEO 


PUT_SPRITEO handles the display of size 0 Sprite 


objects. 
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4, PUT_SPRITE1 


PUT_SPRITE1 handles the display of size 1 Sprite 


objects. 


5 PUT_COMPLEX 


PUT_COMPLEX calls PUTOBJ for each of its 


component objects, 


Parameters: 


OBJ_DEF 


BCKGND_ SELECT 


High level definition of an 
object. See Appendix B for 


further details. 


Used with mobile objects or 
complex objects with a moblle-type 
component. Can be ignored other- 
wise. For methods of selecting 
background colors in a mobile 
Object. Refer to Appendix B for 


additional information. 
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SECTION IV 
INTERRUPT HANDLING AND WRITE DEFERRAL 
\ 
The 60Hz (50Hz for European version) non-maskable interrupt (NMZ) 
in the ColecoVision System has a wide variety of applications 
Such as Providing a fixed time base for the timing Software, and 
a natural debounce interval for the controller interface, 


However, interrupts can cause problems if not handled propérly. 


Let us Say, for example, that the System is in the midst of a 
cail to PUTOBJ ang 25, An fact, writing to VRAM when the 
interrupt occurs. If the interrupt service routine calls for 
transferring data to another area of VRAM by Setting up the Vpp 
address register (auto-increment) to a different value, the 
pending VRAM Operation cannot resume properly after the interrupt 


is serviced. 


The OS contains software which allows Sraphics operations on the 
Object level to be protected against damage by asynchronous 


interrupts. It should be Stressed that the 0S protects ONLY the 
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object level. Routines On the table and chip driver levels could 
e 

be deferred against interrupt by using the application library 

routine, DEF_INT, Suggested in ColecoVision Bulletin No. 0010 


(Appendix D), \ 


In order to implement this Protection for graphics Operations, 
the application Program must allocate Space for a deferra? queue, 
The size of this Queue depends on the number of graphics 
Operations that are expected to be performed between NMIs, but 
usually fifteen entries of three bytes each will prove 
Sufficient. The address of the queue should be passeg on to the 
OS using a routine called INIT_WRITER which also empties the 
queue and prepares it for operation, Thereafter, whenever the 
flag byte DEFER WRITES is set to true (1), calls to PUTOBJ are 
deferred by Placing them on the queue where they may be performed 


using a single OS call from the interrupt service routine. 


In addition to the buffer in which the queue resides, the 
deferral routines use Several defined Storage areas in the course 
of their operation. These are; QUEUE SIZE, QUEUE HEAD, 

QUEUE TAIL, HEAD ADDRESS, TAIL_ADDRESS and BUFFER, They are all 


related to the state of the queue. 
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4.1 INIT_WRITER 
Calling Sequence: 


LD A, SIZE 
LD HL, LOCATION 
CALL INIT WRITER 


Description: 


INIT _WRITER initializes the queue. It does not, in 
fact, do anything to the "Physical" queue in RAM. 
Instead, it merely sets up its desordption by setting 
QUEUE _SIZE to SIZE, HEAD ADDRESS and TAIL ADDRESS to the 
beginning of the buffer and QUEUE HEAD and QUEVE TAIL to 


0. 
Parameters: 


SIZE The size in entries of the queue. 


SIZE should be equal to the amount 
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Ee: 


Of space allocated for the queue 


Givided by three, Range for SIZE 


is 1 to 255, 


\ 
LOCATION The location of CRAM area 


allocated for the queue, 


Side Effects: 
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4.2 WRITER 


Calling Sequence: 


CALL WRITER 


Description: 


WRITER performs any deferred PUTOBJ Operations that may 


be on the queue emptying the queue as it goes. WRITER 


Should be called by the interrupt service routine. 


WRITER uses a "back door" into the PUTOBJ software 


without ever making an explicit Call to PUTOBJ, 


Side Effects: 


0 
t7 


Destroys AF, BC, DE, HL, IX, IY, BC', DE' and 


So HD > PD PD a el ce — eo —) 
Ann wwe © 6 ES SF So an & S = S0 © wm a A wT wR & bo 


COLECOVISION PROGRAMMERS! MANUAL 
5 


Rev. 
1 ©Coleco Industries, Inc. 1982 
CONFIDENTIAL DOCUMENT - DO NOT COPY 5-1 
SECTION v 


TIMING SOFTWARE 


Timing software enables the user to Specify a preset length of 
time and to Signal the usep when that time has elapsed. [In 


theory, up to 255 software timers are available to the user, 


The Z80-CPU's non-maskable interrupt (NMI) input, which comes 
from the VDP interrupt Output, forms the time base for al] the 
timers. In the U.S., it is about every 1/60 second. In the 
European version, it is about every 1/50 second. TIME MGR is the 
routine responsible for generating the time base at the desired 
intervals, 


All timer routines use a CRAM area designated as the TIMER 


The size of this table depends on the number of timers in use and 
their types. There are two types of timers, non-repeating and 


repeating. 


The user will be notified of the status of the timer only when he 


checks it, 
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5d Non-Repeating Timers 


These timers will not repeat themselves after time out. 


The user will be notified ang their timers are Set free, 
\ 


Dae Repeating Timers 


These timers only need to be set once. After each time 


out they will notify the user ang repeat themselves, 


For both types of timers, the timer length can be either 


Short or long: 


(a) Short -] to 255 units of time base, 


(b) Long = 256 to 65535 units of time base. 
ore TIMER_TABLE: 
As a timer is requested, it is placeg into TIMER TABLE. 


Each timer consists of a Mode Byte and a two-byte 


Value_Word. 
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The appropriate amount of CRAM Should be reserved using 


the following formula: 


TIMER_TABLE DEFS Num_of_Timers * 3) 
TIMER_DATA_BLOCK DEFS Num_of_Long Repeating * 4 


NOTE: Num_of Timers is the total number of timers, 
Mode_Byte 

Mode Byte is one byte of data for each timer containing 
the information of done bit, repeat bit, free bit, long 
bit and last-timer-in-table bit (Refer to Appendix G 
for details), ‘ 


Value Word 


A two-byte value which can have several meanings 


depending on the type of timer. 


(a) Short Timers: 


The Value Word is the actual timer in this case. 


COLECOVISION PROGRAMMERS! MANUAL 
5 


ele Industries, Inc. 1982 
) CONFIDENTIAL DOCUMENT - po NOT COPY 5-4 

1 The first byte is the value to be decremented ang 
& | the second byte is the initial ‘timer value. In the 
s . case of a repeating timer, the second byte is useq 
4 to restart the timer. 

5 \ 

6 (b) Long Non-Repeating Timers: 

7 The Value Word is the value of the timer and ‘s 

8 decremented as a tyo-byte quantity. 

9 

10 (c) Long Repeating Timers: 

i) The Value Word is the address of the location in 
12 | the TINER_DATA_BLOCK where the first word is the 
13 value to be decremented and the second word is the 
14 initial timer value. 

15 

16 | 5.3.3 TIMER_DATA BLOCK 

17 

18 | This is the data area in CRAM where four bytes are 

19 : designated for each long repeating timer. The table's 
20 : Size is expandable under user control, so care should be 
21 f taken not to write over other pertinent data. 

22 

23 

24 
25 


»S 
n 


apes 


COLECOVISION PROGRAMMERS! MANUAL 
5 


Rev. 

©Coleco Industries, Inc, 1982 

CONFIDENTIAL DOCUMENT ~ DO NOT copy 5-5 
e 

5.4 INIT_TIMER 


Calling Sequence: 


LD HL, TIMER_TABLE 
LD —*=DE, ~‘TIMER_DATA BLOCK 


CALL INIT TIMER 
Description: 


INIT_TIMER initializes timer data areas to the locations 


defined as inputs, 
Parameters: 


TIMER_TABLE This is the CRam address where the 


timer information will be placed, 


TIMER_DATA_BLOCK This is the address where long 
repeating timer data will be 


placed, 
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Side Effects: 


- Destroys DE and HL. 
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| 5.5 TIME_MGR ° 


Calling Sequence: 


CALL TIME_MGR 


Description: 


TIME_MGR is responsible for maintaining all OS software 
timers. The task of maintenance is defined as updating 
all timers, Setting the proper Signal code when a simep 


times out, and restarting repeating timers. 


Each call to TIME _MGR will cause all active timers ‘to be 
decremented by one. There is no limit as to when the 
routine could be called, but typically it is every x¥I 


from VDP which forms the System time base. 


An active timer is defined as a timer with its repeat 


bit set or its done bit not set, or both. 
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If an entire timer value decrements to zero, the done 


| bit will be set in Mode Byte. In addition, the timer 


will be restarted if it is a repeating type. 


Parameters: None. 


Side Effects: 


- Destroys AF, DE and HL. 
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oT 


REQUEST_SIGNAL 
Calling Sequence: \ 


LD HL, TIMER_LENGTY 
LD A, REPEAT 
CALL REQUEST SIGNAL 


Description: 


REQUEST_SIGNAL accepts a time interval ang &@ repeet code 
(Boolean) as input. The REPEaT parameter, when set, 
instructs TIME MGR to re-initialize-the timer when 1+ 
times out insteag of relinquishing the timer memory 


locations. 


REQUEST_SIGNAL sets up @ timer and assigns that timer a 
number in the accumulator. The routine also determines 
the type of timer and allocates Space in the TIMER_TABLE 


accordingly. 
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Short Timer: 
A short timer has a counter value of 255 or less and 


uses one Mode Byte and Value_Word. 


Long Timer: ; . 


A long timer has counter values greater than 255, 


(a) Non-Repeating: 
A non-repeating timer uses a Mode Byte and 


Value Word. 


(b) Repeating: 
A repeating timers uses a Mode_Byte and Value Word 
in addition to four bytes starting at the first 


available location in the TIMER_DATA_ BLOCK. 


The user should save the timer number. This value, 
referred to as SIGNAL _NUM, should subsequently be used 
when calling TEST_SIGNAL to find the Status of the 


Signal or when calling FREE SIGNAL to release a timer. 
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Parameters: 


TIMER_LENGTH 


Output: 


Side Effects: 


The number of the time base units 
Of a timer. Values range from 1 
\ 


(shortest) to OFFFFY (longest). 


1 = repeating timer; 


0 = non-repeating timer. 


Value of timer number returned in 
accumulator. User Should save it 


in CRAM location SIGNAL NUM. 


- Destroys AF, BC, DE, and HL. 
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Calling Sequence: ’ 


LD A, -SIGNAL_NUM 
CALL TEST SIGNAL 


Description: 


TEST_SIGNAL takes a Signal number and tests to see 
whether the indicated timer has timed out since the last 
time it was tested. If SO, it returns with "true" in 
the accumulator; otherwise, it returns "false", The 


zero flag reflects the contents of the accumulator, 


If the timer of SIGNAL_NUM tested has its Done bit set 
and the timer is non-repetitive, then the Free bit will 


be set to release the timer for further use, 


If no timer of a Particular signal number exists then 


the routine Will return a false, 


COLECOVISION PROGRAMMERS! MANUAL 


Rev. 
©Coleco Industries, Inc. 1982 
CONFIDENTIAL DOCUMENT - Do NOT COPY 5-13 


Although it has been defined that testing a non-existing 
Signal number will return a false Value, a common error 
in use of timing routines is the testing of an undefined 


Signal. 

The error occurs when one module, with a given 
SIGNAL NUM, calls TEST_SIGNAL with that SIGNAL _NUM as 
input. If this module receives a "true" from 
TEST_SIGNAL, then another module which 4s rightfully; 
uSing a timer with that SIGNAL_NUM will not receive 

a "done" signal. 

Parameters: 

SIGNAL NUM Timer number. 


Side Effects: 


- Destroys AF (output), BC, DE, and HL, 
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5.8 FREE SIGNAL 


Calling Sequence: 


LD A, SIGNAL _NUM 
CALL FREE SIGNAL 


Description: 


FREE SIGNAL takes a SIGNAL NUM value as input and upon 
finding a timer assigned to that number, releases it to 
the free list. If no timer of that SIGNAL NUM is found, 
no action will be taken, This routine will free a timer 


regardless of its current value or its REPEAT parameter, 


Special case of long repeating timer: 


This routine will release a portion of the 


TIMER_DATA_BLOCK that a Particular timer uses and moves 


the remaining contents up. The Value_Words of other 
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repeating timers will also be modified to reflect this 


move. 


NOTE: In this special case, TIME_MGR, or any other 
routine that accesses or modifies the 
TIMER_TABLE, should NOT be called during the exe- 
cution of FREE SIGNAL. (This may occur if 
TIME_MGR was called on interrupt). ColecoVision 
Bulletin No. 0010 (Appendix D) suggests the 


Solution of using DEF_INT to defer interrupts, 


Parameters: 


SIGNAL NUM Previously defined output from 


REQUEST_SIGNAL. 


Side Effects: 


- Destroys AF, BC, DE and HL. 
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repeating timers will also be modified to reflect this 


move. 


NOTE: In this Special case, TIME_MGR, or any ether 
routine that accesses or modifies the 
TIMER_TABLE, should NOT be called during the exe- 
cution of FREE SIGNAL. (This may occur if 
TIME_MGR was called on interrupt). ColecoVision 
Bulletin No. 0010 (Appendix D) Suggests the 


Solution of using DEF_INT to defer interrupts, 


Parameters: 


SIGNAL NUM Previously defined output from 
REQUEST_SIGNAL. 


Side Effects: 


- Destroys AF, BC, DE and HL. 
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SECTION VI 


CONTROLLER INTERFACE 

a \ 
Most applications involving the hand controller require similar 
needs in decoding and debouncing figs inputs. The operating 
System addresses those needs in one general Purpose routine, 
POLLER. POLLER will decode and debounce either all or selected 
Portions of the hand controller hardware and place the processed 
data in the Controller Data Area selected by the pointer in 


CONTROLLER_MAP. 

Special applications may require non-standard decoding of the 
inputs available from the hardware; therefore, entry points to 
lower level routines are available. 


There are four routines available to access controller inputs: 


POLLER 


DECODER 


CONT_SCAN 


UPDATE SPINNER 
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6.3 Controller Data Area 
e 
The pointer in CONTROLLER_MAP points to the user-defined 
CRAM area which is accessed and/or modified when POLLER 
is called. Users define this address by piteter the 
location of the 12 bytes of the CRAM Controller Data 
Area at cartridge location CONTROLLER_MAP. They are 


Gefined as follows: 


+0 Player 1 enable 

+1 Player 2 enable 

+2 Fire button (left button) Player 1 
+3 Joystick Player 1 
+4 Spinner count (for interface modules) Player 1 
+5 Arm button (right button) Player 1 
+6 Keyboard Player 1 
+7 Fire button Player 2 
+8 Joystick Player 2 
+9 Spinner count Player 2 
+10 Arm button Player 2 
ae | Keyboard Player 2 


{ 
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Player Enable (+0, +1): 


Bit 7 Bit 0 
ep ES 
Where bit = ]: Function enabled, \ 


bit = 0: Function disabled, 


xX Don't care 


While functions are @as follows: 


ty 

pu. 

ct 

~) 
' 


= Controller Enable 


Bit f= Keypad 


Bit 3 = Arm Button 
Bit l= Joystick 
Bit 0 = Fire Button 


Status of individual Portions of the Controller map ares 


when enabled is described as follows: 


Fire button: 


Status = O40H, if fire button pressed 


" 


Status OH, if fire button not pressed 
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Joystick: 
° 

Status Direction 
O1H N 
03H NE 
02H E 
06H SE 
O4H S 
OCH SW 
08H W 
09H Nw 


Spinner Switch: 


SPIN _SW_CNT is added to the value for position 


(Ref to Sec. 6.5) 


Arm Button: 


Status 


Status 


" 


OO40H if arm button pressed 


OOOOH if arm button not pressed 


offset. 
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Keypad: 


PY 
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POLLER 


Calling Sequence: 


CALL POLLER 


Description: 


Reads, decodes and debounces all active 


ct 


controllers. The results are placed in 


Data Area. 


POLLER's debounce algorithm waits until 
data the same for two successive passes 
modifies the Controller Data Area. If 
portion is disabled, then this routine 
looking for the second occurrence upon 
Please note that the POLLER routine can 


itself. 


6-6 


portions of both 


the Controller 


it finds the 
before it 
a particular 
will still be 
re-enabling. 


not interrupt 
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Side Effects: 


e 
-Destroys all except alternate register pairs, does not 
destroy aiternate AF pair. 
- Zero's SPIN_SW_CNT if that portion of the eonttoller 


is enabled. (See UPDATE SPINNER). 
Calls to other OS routines: 


- CONT SCAN 
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6.3 DECODER e 


Calling Sequence: 


LD H, CNTRLR NO, 
LD L, CNTRLR SEGMENT NO. 


CALL DECODER 
Description: 


DECODER calls CONT SCAN; decodes and returns as output 
according to the controller Segment requested. Decoding 
uses the same format as the individual status bytes in 


Controller Data Area. 


Parameters: 
CNTRLR NO. O = Player 1's controller only 
1 = Player 2's controller only 
CNTRLR The value found in Segment number 
SEGMENT NO, will decode these respective 


portions of the controller: 


o ons HD HH wR & 1 we 


some ek BB hw BP & eee eB ee ee Gy 
awe Pe Se FY OO mW ome mw Oe Ot OU CUS 


COLECOVISION PROGRAMMERS' MANUAL 


1 Rev. 5 
| ©Coleco Industries, Inc. 1982 
| CONFIDENTIAL DOCUMENT - Do NOT COPY 6-9 


oO 
" 


Fire,Joystick, Spinner 


| 1 = Arn, Keypad 


OUTPUTS: IF SEGMENT CHOSEN WAS: 
eee er =e Veen WAS S ‘ 

Segment 0 Segment 1 
Register H Fire Arm 
Register L Joystick Keyboard 
Register E Spinner 


The decoded values are listed in the Controller Daca 


Area. 


Side Effects: 


- Destroys AF, BC, DE and HL. 


Calls to other OS routines: 


- CONT_SCAN 
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6.4 CONT_SCAN 


Calling Sequence: . \ 


CALL CONT SCAN 


Description: 


Reads the actual ports to both controllers and places 


the data in an OS-defined CRAM area. These locations 


are labeled as SO_CO, SO_Cl, S1_CO and S1_Cl. 


Side Effects: 


- Destroys AF. 
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6.5 UPDATE_SPINNER 


Calling Sequence: 


ORG 801EH 


JP UPDATE SPINNER 
Description: 


For use with expansion modules only. Interrupt service 
routine which processes controller Spinner switch 
interrupts (maskable). Decrements OS reserved byte 
SPIN_SWO_CNT for Controller No. 0 or SPIN_SW1_CNT for 
Controller No. 1 if spinner is going in one direction; 
increments byte if spinner is going in the other 


direction (Ref. Table 10-1). 


NOTE: SPIN_SW_CNT is accessed and modified by both 


DECODER and POLLER if they are called. 
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SECTION VII 
SOUND GENERATION SOFTWARE 
\ 
The OS provides sound generation routines that output frequency, 
attenuation and control data to the TI SN76489 sound generator 
controller. The "sound" described in this section can be repre- 


Sented as both music or noise. 


There is at least one ten-byte block of CRAM called a "Sound Data 
Area" reserved for each sound channel. This area contains a 
record of the current values "playing" on that sound channel. 
These values are the timing and descriptive information which 
generate musical notes that are originally stored in cartridge 
ROM. In total, there should be a minimum of four sound data 
areas reserved by the user, one for each channel. More data 
areas are needed if there are sounds to be played concurrently. 


For an average video game, seven is the required number. 


Basically, in order to generate sound effects, the user has to 
Prepare music notes and call the sound generation routines. The 
notes Seiten, pointer and four routines are described below. For 
detailed information, refer to the Sound Users' Manual in 


Appendix C. 
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7.1 LST_OF_SND_ADDRS and PTR_TO LST OF SND _ADDRS 


All the music notes for an application program starts at 
the address called LST_OF_SND_ADDRS in cartridge ROM. 
There is another dedicated CRAM pointer located at 
address PTR_TO_LST_OF_SND_ADDRS which points to the 
LST_OF_SND_ADDRS. It is the user's responsibility to 
set up the pointer before passing control to any sound 


generation software. 


SOUND_INIT 

This routine should be called immediately after power 
on, before any sound processing can occur. It turns off 
the sound generators, initializes the CRAM locations to 
be used as sound data areas, sets up the four channel 
data area pointers and initializes 


PTR_TO_LST OF SND _ADDRS. 


INPUT: - on 

TYPE: 8-bit constant 

PASSED: in B 

DESCRIPTION: Number of sound data areas used by 
the game. 
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INPUT: LST_OF_SND_ADDRS 
TYPE: 16-bit address e 

PASSED: in HL 

DESCRIPTION: LST_OF_SND_ADDRS is the base 


address of a list of the starting 
addresses for each sound's note 


list and data area. 


OUTPUT: 1. Turns off all sound 
generators. 

2. Initializes 
PTR_TO_LST_OF_SND_ADDRS. 

3. Writes the inactive code 
(OFFH) to byte 0 of the n 
sound data areas. 

4. Stores 00 at end of sound data 
areas. 

5. Sets the 4 channel sound 
pointers to a dummy inactive 
area. 

6. Sets SAVE_CTRL to OFFH. (See 


"Noise Notes" discussion in 
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(es) 


ColecoVision Sound Users! 


Manual in Appendix C). 


PLAY IT 


PLAY_IT is called to start a sound. Using a sound 
number passed in B, PLAY_IT loads the data for the 
sound's first note into the appropriate sound data area, 
thereby truncating whatever sound had been "playing" in 
that data area. (The address of the appropriate area is 
found by using the sound number as an index into the LST 
OF_SND_ADDRS table). It also formats the data area's 
header and sets up the next note pointer. If the sound 
is a Special sound effect, its next note pointer is set 
to the address of the special effect routine. The next 
time PLAY_SONGS is called, that sound's first note will 


be played. 


If PLAY_IT is called with a sound number of a sound 
which is already in progress, it returns immediately 


(1.e., it doesn't restart the sound). 
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INPUT: Sound number to be started. 
TYPE: 8-bit constant, 1 to 61. 
PASSED: In B. ; 
CALLS: PT_IX_TO_SxDATA, \ 
LOAD_NEXT_NOTE PTR, 
UP_CH_DATA_PTRS. 
OUTPUT: 1. Moves the sound's first note 


data to the appropriate sound 
data area. 

2. Formats byte O header of the 
sound's data area. 

3. Points next note pointer in 
data area (bytes 1 & 2) to 
address of first note in 
sound, or address of special 


sound effect routine. 
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7.4 SOUND_MAN 


SOUND_MAN should be called every VDP interrupt. For 
each data area, SOUND_MAN processes the appropriate 
timer and sweep counters ahd modifies the frequency and 
attenuation data accordingly. If the data area is 
assigned to a special effect, SOUND_MAN calls that 
effect. When a note is finished, SOUND_MAN, using the 
data area's next note pointer, moves data for the next 
note of the sound into the area. If SOUND_MAN reads a 
header byte (in Cart ROM) that has bits 3 and 4 set, 
indicating repeat sound, it will start the sound again 
by reloading the first note in the sound. 

After the operations upon a data area have been per- 
formed, if necessary, the channel data area pointers 
(PTR_TO_S_ON_x) are updated. The following data areas 
are processed in the same fashion, in order of 
occurrence, until the end of data area code, 00, is 


reached. 
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SOUND_MAN does not output the modified frequency and 
attenuation data. PLAY SONGS is called Just before 
SOUND_MAN to do this. 


\ 
Special codes in byte 0 of the sound data area indicate: 


255: Data area inactive, do no processing; 
62: A special effect is to be Played; SOUND_MAN calls 
the effect routine; 
0: End of sound data areas (SOUND_MAN processes data 
areas until it sees 0 in byte 0). 
NOTE: Sound number 1 MUST use the first area in the 
block of sound data areas. SOUND_INIT uses this 


address to find the sound data area. 


INPUT: None. 
CALLS: Pr IX TO SxDATA, 
PROCESS _DATA_AREA. 


OUTPUT: Calls routines which: 
1. Decrement sound duration and 


Sweep timers. 
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7.5 


2. Modify Swept frequency and 
attenuation values. 

3. Call special effects routines 
where necessary. \ 

4. Update the channel data area 
nédaters if necessary. 


5. Restart the sound if 


indicated. 


PLAY_SONGS: 


PLAY_SONGS takes the frequency and attenuation data 
pointed to by the four channel data area poinGers 
(PTR_TO_S ON |X) and outputs it to .the four sound chip 


generators. 


INPUT: None. 
CALLS: TONE OUT, UPATNCTRL. 
OUTPUT: 1. Current frequency and 


attenuation data is output to 
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e 


 . & 


each tone generator, if sound 
on that channel is active; if 
Sound on that channel is 
inactive, that Eener ener is 
turned off. 

2. Noise generator is sent 
current attenuation data and 
control data, if new. 

3. Modifies SAVE CTRL if 


necessary. 


7.6 Application 


These four routines would normally be called as follows: 


Begin 
Power on inits done by OS 
Cartridge program receives control 
LD B, number of song data areas used in the 


game 


LD HL, address where LST_OF_SND_ADDRS is 


store in ROM. 
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| 
End 
| 
| 


CALL SOUND_INIT to initialize sound data areas 
e 

Whatever other power on inits you want to do 

Start game 


e ‘ 


LD B, number of sound you want to start 


CALL PLAY_IT to set up for start of sound 


VDP interrupt occurs: 

CALL PLAY_SONGS to output data 

CALL SOUND_MAN to process sound data 
Whatever else you want to do during VDP 
interrupt 


RETN to game 
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SECTION VIII 
BOOT-UP SOFTWARE 


.. Power-Up Procedure 


begin (*run from 0*) 
set up stack_pointer 
(*power up#®) 
if cartridge type = test 
execute the code at starting address 
found in location B00AH( Loge By pe ) 
else | 
Gisable sound chip ». 
init random number generator 
init controller buffer areas 
defer writes = false 
mux sprites = false 
(*display_logo®) 
fill VRAM with O's 
set up VDP to mode l 


load ASCII generators 
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load logo generators 
load logo names 
load logo colors 
enable display \ 
if cartridge = game 
display logo and game name 
wait l2 seconds 
disable display 
execute the code at starting 
address found in location 800AH 
else (*cartridge not present*) 
display log and "insert cartridge" 
message 
wait 60 seconds 
disable display 
soft halt 
endif ("cartridge = game*) 
endif (*cartridge type = test*) 


end (*run from 0*) 
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Title Screen 


During the power-up process, the boot-up software will 


look for an ASCII string of characters at Cartridge ROM 


location GAME NAME for display on the logo screen. 


The following information should be in the string: 
Ls Cartridge title with trademark (T=1EH, M=1FH), 


ee Original licensor of the game. 


Si The year the cartridge is released. 


Example: 
DEFB "DONKEY KONG JUNIOR",1EH,1FH 
DEFB /PRESENTS NINTENDO'S/1983" 


Each string is delimited by a slash (/). The first two 


Strings are limited to 28 characters and the last string 


is four characters. 


Cartridge Present Identifier: 


All cartridges must store OAAH at location 8000H for the 


OS to recognize them as cartridges that require logo 


display. 
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The OS will initialize portions of the hardware, select 
@ 
data areas, display the logo screen and then pass 


control to the cartridge program. 
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SECTION IX 


MISCELLANEOUS UTILITIES 
9.1 | ADD816 
Calling Sequence: 
LD A, VALUE 


LD HL, ADDRESS 
CALL ADD816 


Description: 


ADD816 adds an 8-bit signed number in accumulator to a 
16-bit unsigned number pointed to by HL; returns with 


altered 16-bit number at the HL address. 


Parameters: 


VALUE 8-bit signed number. 
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ADDRESS Address pointing to a 16-bit 
e 


unsigned number 

Output: Two-byte value at the address 
Pointed to by the HL register 
pair. 


Side Effects: 


Destroys registers A, F and B. 
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DECLSN 


1 
. - 
2 Calling Sequence: 
$ 
4 LD —«xHL, ADDRESS : 
5 CALL DECLSN 
J - 
7 Description: 
& 
9 DECLSN decrements least Significant nibble of a byte 
10 Pointed to by HL without affecting most Significant 
1] nibble or HL. Returns with altered 8-bit number at HL 
12 address. Sets 2-flag if 0, C-flag if -1, 
13 
14 Parameters: 
15 
16 ADDRESS Address pointing to an8-pbit 
17 unsigned number. 
18 
19 Output: A one-byte value at the address 
20 Pointed to by the HL register 
21% | pair. 
22 ° 
Side Effects: 
23 
24 Destroys A and F, 
“35 


do 
n 
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9.3 DECMSN ' 


Calling Sequence: 


LD EL, ADDRESS . 


CALL DECMSN 


Description: 


DECMSN decrements the most Significant nibble of byte 
Pointed to by HL without affecting the least Significant 
nibble or HL. Returns with altered 8-bit number at HL 


address. Sets Z-flag if O, C-flag if -1. 


x 


Parameters: 

ADDRESS Address pointing to 8-bit unsigned 
number. 

Output: A one-byte value at the address 


pointed to by the HL register 


pair. 


Side Effects: 


Destroys A and F, 
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9.4 MSNTOLSN ‘. 


Calling Sequence: 


LD HL, ADDRESS 
CALL MSNTOLSN 


Description: 


MSNTOLSN copies the most significant nibble of byte 
pointed to by HL to the least significant nibble of that 
byte. .The routine returns the results at the location 


pointed to by HL. 


Parameters: 

ADDRESS Address pointing to an 8-bit 
unsigned number. 

Output: A one-byte value pointed to by HL 


register pair. 


Side Effects: 


Destroys A, F and B. 
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9.5 RAND_GEN 


Calling Sequence: 


CALL RAND_GEN 


9-6 


Description: 


RAND_GEN is a 16-bit psuedo random number generator. It 


"exclusive OR's" the 15th and 8th bit together and then 


rotates the entire Quantity to the left and inserts the 


"exclusive OR'ed" bit into the rightmost bit. Upon 


leaving, it stores the random number at global location 


RAND_NUM. 


Output: 


Side Effects: 


a 


The random number can be found in 
the HL register pair or RAND_GEN 
because RAND GEN contains the 

value of L while RAND GEN + 1 has 
the value of H, or in the accumu- 


lator because A = L before RET. 


Destroys registers AF and HL (return values). 
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9.6 LOAD ASCII 


Calling Sequence: 


CALL LOAD_ASCII 
Description: 


LOAD _ASCII writes out the ASCII generator set to the 
pattern generator table. The ASCII table is located in 
Cartridge ROM Starting at ASC_TABLE, INIT TABLE must be 
called to set up the table addresses before using this 


routine. 


Side Effects: 
Destroys AF, DE, HL and IY. 


Calls to other OS routines: 


- PUT_VRAM 
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SECTION X 
DEFINED REFERENCE LOCATIONS 


10.1 OS ROM 7 


In the OS ROM area, it is IMPORTANT to know that the 
application programs should only use the OS entry points 
listed in the OS SYMBOLS file. Accessing to the OS 
otherwise is illegal and may cause program malfunction 
when hardware configuration changes or OS routines 
relocated due to update. The jump table starts from 
location JUMP_TABLE through the end of OS ROM. Lt 
contains all the subroutine entry setae released to the 


user. 


At the beginning of the cartridge, there are eight 
Programmable restarts at addresses O0008H, 0010H, 0018k, 
O0020H, 0028H and 0030H. Each of the restarts jump to a 
location in Cartridge ROM where a vector can be provided 
to access an OS entry point. The Z80A-CPY hardware also 


designates location 0038H to Service maskable interrupt 
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(MI) and location 0066H to service non-maskable 
interrupt (NMI). Jump instructions tre provided for 
these two reference locations for the user to implement 
interrupt vectors in Cartridge ROM. Starting at 
location 0069H is the OS ROM data area which conten 
the AMERICA byte, ASCII table address and numeric table 
address. Figure 10-1 is the OS ROM map showing all the 
reference locations mentioned above. Appendix E lists 


all entry points of the Jump Table. 
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nn San 
0008H 
003BH 


0066H 
0069H 
OS ROM DATA 
AREAS 
O006EH 
<< OS ROUTINES (we 
1F61H ; : 
JUMP TABLE 
1 FFFH 
Figure 10-1 7 
OS ROM MAP 


LO «lod Europe/America Byte: 


The European TV uses PAL system (625-line format) which 
requires interrupt at the end of each active-display 
Scan every 1/50 second, as opposed to every 1/60 second 


for the US model (NTSC, 525-line format). 
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ColecoVision cartridges must be interchangeable between 
both systems, the Europe/America byte at AMERICA in OS 
ROM, has been established to detect which version of the 
unit is in use. If a real-time Gisplay (such at a 
clock) must be implemented, .the program will have to 
access the Europe/America byte to determine the current 
line frequency. For America-based units, this location 
will contain 60 (3CH) and for European-based units, it 


Will contain 50 (32H). 
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10.1.2 


as 


Restart Vectors = 


Figure 10-2 shows the eight programmable restarts their 


addresses and corresonding locations in Cartridge ROM. 
\ 


: JUMP TO 
OS ADDRESS CART. ROM ADDR. - 
0008H 800CH 
0010H 800FH 
0018H 8012H 
0020H 8015H 
0028H 8018H 
0030H 801BH 
Figure 10-2 
OS RESTARTS 


For each of the restart locations above, there should be 
a vector in Cartridge ROM provided by the user. To use 
a restart, the user must place a jump instruction to the 
address of the routine which he or she wishes to access 
through the Cartridge ROM vector; for example, 


JP WRITE VRAM at 800CH. These routines are usually the 


ones most frequently used in order to save application 


program space. 
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10.1.3 


10.2 


Graphics Tables * 


There are two graphics tables in the OS available to the 
user. The pointers for the ASCII table and Number table 
are defined in the locations of ASCII-TABLE and 


NUMBER_TABLE. 


The ASCII table contains pattern generators for all 26 
upper and psuedo-lower (half-size upper) case letters 
Plus eleven special characters in 5x7 dot matrix form. 
The number table contains pattern generators for the 


numbers from 0 to 9 plus seven Special characters, 
Cartridge ROM 


At the beginning of Cartridge ROM, locations are 
reserved for testing cartridge presence (Section 8-3), 
plus a number of pointers which point to tables, buffers 


and start of the game. On top of the pointers there are 
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Spaces allocated for restart (Ref. Figure 10-2) and 

interrupt vectors. There are up to 68 bytes available 
to the user starting at location GAME_NAME, to name the 
cartridge, their Format has been described in the title 


\ 
screen in section 8.2. Figure 10-3 shows the cartridge 


ROM map. 
8000H 
Cartridge Identifier 
8002H 
Pointers 
800CH 
Restart Vectors 
801EH 
Interrupt Vectors 
8024H 
Cartridge Title Name 
(variable size up to 60 bytes) 
8060H 
Applications 
Program 
(variable size) 
FFFFH 


Figure 10-3 


CARTRIDGE ROM MAP 


oO oa vs wn wo BR CH NO ow 


i 
fan) 


COLECOVISION PROGRAMMERS' MANUAL 


Rev. 5 
©Coleco Industries, Inc. 1982 
CONFIDENTIAL DOCUMENT = DO NOT COPY 10-8 
20.3 CRAM Areas 
, e 
7000H 


per 


7020H 
702AH i - 
User RAM 7 
T3B9H Stack 
73BAH 
73FFH 
Figure 10-4 
CRAM MAP 


Figure 10-4 is the CRAM Map. Eleven bytes are reserved 
for OS sound data starting at 7020H; seventy-one bytes 
at the high end of memory are used by various OS 
routines. The top of the stack is sitting at address 
73B9H which grows in the decrementing direction. 

Between stack and user buffer there are 942 bytes 
available for the application program. However, care 
Should be exercised in both size and boundary when using 


CRAM as scratch pad. 


Table 10-1 lists all reserved CRAM areas for user 


reference. 
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:: Table 10-1 

| DETAILED CRAM REFERENCE LOCATIONS 

7000H (Start of user RAM) 

| PTR_TO_LST_OF_SND_ADDRS 7020H (OS Sound Data Area) 

+1 : 7021H : 
_ PTR_TO_S ON_O 7022H 

| +1 7023H ° 

|, PTR_TO_S ON 1 7024H 

| #1 7025H 

PTR_TO_S ON 2 7026H 
41 7027H 
| PTR_TO_S ON 3 7028H 

f 4a 7029H 

| SAVE_CTRL 702AH 

| 702BH (Resume user RAM) 

| STACK 73B9H (Top of Stack) 

| PARAM_AREA 73BAH (Parameter passing area for 

fF 6+] 73BBH Pascal calls to OS routines) 

| 42 73BCH 

| 43 73BDH 
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+4 

+5 

+6 

| 

+8 
VDP_MODE_WORD 
+1 ; 
VDP_STATUS BYTE 
DEFER_WRITES 
MUX_SPRITES 
RAND_NUM 

+1 

QUEUE_SIZE 
QUEUE_HEAD 
QUEUE_TALL 
HEAD_ADDRESS 
+1 

TAIL ADDRESS 
+1 

BUFFER 

+] 


TIMER_TABLE BAS 


7T3BEH 
73BFH 
73C0H 
73C1H 
73C2H 
73C3H 
73C4H 
73C5H 
73C6H 
73C7H 
73C8H 
73C9H 
73CAH 
73CBH 
73CCH 
73CDH 
73CEH 
73CFH 
73D0H 
73D1H 
73D2H 


73D3H - 
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+1 73D4H 

NEXT_TIMER_DATA 73D5H ° 


+] 
DBNCE_BUFF 
+1 
+2 
+3 
+4 
ae 
+6 
+7 
+8 
+9 
+10 
#11 
#12 
+13 
+14 
+15 
+16 
+17 
+18 


73D6H 

73D7H (FIRE_OLD - Player 0) 
73D8H (FIRE_STATE - Player 0) 
73D9H(JOY_OLD - Player 0) 

73DAH (JOY_STATE - Player 0) 
73DBH(SPIN_OLD - Player 0) 
73DCH(SPIN_STATE - Player 0) 
73DDH(ARM_OLD = Player 0) 
73DEH(ARM_STATE - Player 0): 
73DFH(KBD_OLD - Player 0) 
73EOH(KBD_STATE - Player 0) 
73E1H(FIRE_OLD - Player 1) 
7T3E2H(FIRE STATE - Player 1) 
73E3H(JOY_OLD - Player 1) 
73E4H(JOY_STATE - Player 1) 
73E5H(SPIN_OLD — Player 1) 
73E6H(SPIN_STATE - Player 1) 
73E7H(ARM_OLD - Player 1) 
73E8H(ARM_STATE- Player 1) 
73EQ9H(KBD_OLD - Player 1) 
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+19 
SPIN_SWO_CT 
SPIN_SW1_cT 
STROBE_FLG 
SO_CO 

SO_Cl 

S1_co 

S1_C1 
VRAM_ADDR_TABLE 
SPRITENAMETBL 
+] 
SPRITEGENTBL 
+1 
PATTRNNAMETBL 
+1 
PATTRNGENTBL 
+1 
COLORTABLE 

+1 

SAVE_TEMP 

+1 ; 
SAVED_COUNT 


+1 
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73EAH 
73EBH 
73ECH 
73EDH 
73EEH 
73EFH 
73F0H 
73F1H 
73F2H 
73F2H 
73F3H 
73F4H 
73F5H 
73F6H 
73F7H 
73F8H 
73F9H 
73FAH 
73FBH 
73FCH 
73FDH 
73FEH ° 
73FFH 
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1.0 INTRODUCTION 


The material in this manual assumes that the reader is familiar with 
Texas Instruments' 9918/9928 Video Display Processor (VDP). Since the 
system routines assume that the VDP will be Operating in Craphics Mode 
Ioor I1, particular attention should be Given to the discussion of 


these modes. 
° e 


The Colecovision operating system includes several Graphics routines 
to help facilitate the creation and Banipulation of images on the 
Gisplay. These routines and associated data structures enable the 
cartridge programmer to treat graphic elements as conceptual entities 
called “objects", of which there are four types. Each object myey 
consist of one or more “frames". A frame is a single, visual 
Banifestation of the object. 


The graphics routines provide a high-level means of altering the frame 
Gisplayed and the position of objects. 


1.1 SUMMARY OF OBJECT TYPES 
The four possible object types are: 


1. Semi-Mobile 


Semi-Mobile objects are rectangular arrays of pattern Blocks. 
They are always aligned on pattern boundaries but way bleed on 
and off the pattern plane in any direction. Semi-Mobile 
ebjects may be used either for moving images (when incremental 
wction by pattern plane positions is acceptable) or for 
setting up background patterns. 


2. Mobile 


The primary purpose of Mobile objects is to overcome a 
particular limitation of the VDP which Prevents more than 4 
Sprites from being displayed on a given horizontal TV line. 
Mobile objects are always 2 by 2 pattern blocks in sise. They 
may be placed anywhere on the pattern plane with pixel 
resolution and will appear as superimposed upon the 
background. They also may bleed on and off the pattern plane 
in any direction. 


32. Sprite 


Sprite objects are composed of individual sprites. 


4. Complesz 


Complex ebjects are collections of other “component” objects. 
The component objects may be of any type including other 
Comples objects. 
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1.2 DATA STRUCTURE OVERVIEW 


Each object is defined by a “high level definition" in Cartridge RON 
(CROM) which Tinks together several different data areas. The data 
contained within these areas completely Specifies all aspects of an 
ebsject. The following is a brief Gescription of the, different areas. 


CRAPHICS 

This Gata area is also located in CROM. Pattern and color generators 
for Semi-Mobile, Mobile and Sprite objects, and frame data for all 
objects are located in the CRAPHICS data area. The data structure 
within each CRAPHICS area depends on the type of object with which it 
is associated. If, however, two or more objects eof the sane type are 
Graphically identical, they may share the same GRAPHICS data area. 
This will reduce the amount of @raphics data that needs to be stored 
in CROM. 


STATUS 
Each object must have its own STATUS area in CPU RAM. _ The cartridge 
Program uses this area to manipulate the object. This is done by 


altering the Jocation within STATUS which determines which fraze is to 
be displayed as well as the locations which define the position of the 
object on the display. The graphics routine, PUT_OBJECT, when called, 
will access the object's status area and place the object accordingly. 


OLD_SCREEN 

Mobile and Semi-Mobile objects wtilize the pattern plane. They are 
Cisplayed by overwriting an array of the names in the pattern name 
table with an array of names which Tepresents a particular frame of 
the object. The overwritten names can be thought of as representing a 
background frame which is “underneath" the object. Tf the background 
frame will need to be restored to the Gisplay (e.g. when the object 
moves or is removed from the display) then it is necessary to save 
that frame. OLD_SCREEN is a save area for background frames. The 
graphics routines PUT_SEMI and PUT_MOBILE will automatically save and 
restore background frames when an object is moved or its frame is 
changed. OLD_SCREEN may be located in CRAM or in VRAM. 


1.3 CRAPHICS ROUTINES OVERVIEW 


ACTIVATE 

The primary purpose of this routine is to move the pattern and color 
generators from the CRAPHICS data area into the pattern and ccolor 
Generator tables in VRAM. Each object must be “activated” before it 
can be displayed. ACTIVATE also initializes the first byte in an 
object's OLD_SCREEN data area with the value 80H. PUT_OBJECT tests 
this location before restoring the background names to the name table. 
If the value 80H is found, it is an indication that the object has not 
yet been displayed and therefore, there are no saved background names 
in OLD_SCREEN. ACTIVATL initializes a byte (in the case of Mobile 
objects, a word) which indicates where additional generators should be 
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located if such Generators are to be created at game-on time by other 
routines, such as REFLECT_VERTICAL (described elsewhere in the 
COLECOVISION USERS MANUAL). Finally. ACTIVATE will initilalise the 
FRAME variable in the object's STATUS area to 0. 


: ° e 
PUT_OBJECT 
This routine is called when an object's frame or its location on the 
display is to be changed. The routine tests the type of object and 
then branches to one of four other routines Gesigned to handle that 
particular object type. These routines function as follows: \ 


1. PUT_SEMI 

Semi-Mobile objects are Placed on the Gisplay by writing the generator 
names specified by one of the object's frames into the Pattern nase 
table in VRAM. The pattern and color generators which are needed to 
Create the frame must already be in their Tespective generator tables. 


2. PUT_MOBILE 

Mobile objects are Gisplayed by producing a new set of pattern and 
color generators which Gepict the frame to be CGisplayed on the 
background. These new Generators are then moved to the locations in 
the VRAM pattern and color Generator tables which are reserved for the 
object; the names of the new generators are then written into the 
pattern name table. 


3. PUT_SPRITEO 
4. PUT_SPRITE1 
These routines handle the Gisplay of sise 0 and sise 1 Sprite objects. 


S. PUT_COMPLEX 

Complex objects are aggregates of other “component” objects. The 
Positional Telationship of these compontent objects ts defined in an 
offset list. For each of the component objects, PUT_COMPLEYX 
calculates the correct X and Y location, then calls PUT_LOBJECT with 
the address of the high-level éefinition for that component object 
passed in the IX register. 


1.4 SOME KEY CONCEPTS 


META-PLANE 
In order to facilitate moving objects on and off the pattern plane, a 
conceptually larger “meta-plane” has been implemented. Positions on 


the meta-plane are defined with respect to two orthogonal azes, X and 
¥Y. The pattern Plane is contained within the mBeta-plane and its 
Origin is coincident with the Origin of the meta-plane (see fig. 1). 


X_LOCATION 
Y_LOCATION 

These two variables are part of each object's STATUS area. Each 
variable contains a 16 bit Signed number which represents the distance 


CC 
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in pizels from the origin of the meta-plane. The two wariables 
together form.the coordinate location ef the object's upper left 
corner on the meta-plane. Sprite and Mobile ebjects will be G6isplayed 
at the exact location indicated by their £ and Y_LOCATIONs. However, 
since Semi-Mobile objects are always aligned on pattern position 
Boundaries, they will be displayed aligned with theenearest pattern 
Boundary above and to the left ef the indicated X and Y_LOCATIONs. 
When a Complex object is to be Cisplayed, the X and Y_LOCATION of each 
of its component objects is computed by adding a displacement for that 
Component te the Complex object's X and Y_LOCATIONs. Each component 
object is then Gisplayed at the computed location. \ 


To move an object, the X and or Y_LOCATIONs in the CRAM STATUS area 
are changed and then PUT_LOBJECT is called with the address of the 
object's high-level definition passed in the IX register. When Boving 
Mobile objects an additional parameter is passed in register B. This 
is discussed further in the Gescription of PUT_MOBILE. 


FRAME . 
This variable is also part of each object's STATUS area. The value 
contained in FRAME is used by PUT_LOBJECT to select one of several 
pointers (or, in the case of Complex objects, pairs of pointers) which 
point to the data defining the graphic content of the frame. The 
pointers may either point to frazne data which is part eof the original 
ROMed CRAPICS, or they may point to an area in CPU RAM. In the latter 
case, the frame data must be created by the cartriége program before 
thet frame can be Sisplayed. 


The frame of an object is changed by altering the FRAME variable in 
the object's STATUS area. PUT_LOBJECT is then called in the sane 
manner as when moving an object. When changing the frame number of a 
Mobile object, bit 7 of FRAME should not be altered. This bit is 
tTeservecd for use by the PUT_MOBILE routine. 


Ry 
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Since Semi-Mobile ebjects are Gisplayed by altering names in the 
pattern name table, it may be necessary to save the pattern plane 
Graphic which is lost in the process of displaying the Sent-Mobile 
object (see previous discussion ef OLD_SCREEN). The third address in 
the object's high level definition Gesignates a location for Saving 
the overwritten names. If that address is greater than or equal to 
7000H, then the OLD_SCREEN will reside in CPU RAM. g If the address is 
less than 7000H, then OLD_SCREEN will be in VRAM. Finally, if the 
address is 8000H or greater, then the overwritten names will not be 
Saved. 


2.1 DETAILED DESCRIPTION OF SEMI-MOBILE OBJECT 
DATA STRUCTURE 


(Identifiers in eaps refer to symbols in the data strocture Summary) 


Each Seni-Mobile object is defined in cartridge ROM by: 
1) SMO - the object's “high level Gefinition" 
2) CRAPHICS - an area containing the object's graphics data, divided 
into three subsections: 
Parameters and Pointers 
Franes 
Generators 


and in CPU RAM by: 

1) STATUS - a status area 

2) OLD_SCREEN - an eptional location for saving overwritten 
backgounds. (OLD_SCREEN may alternatively be stored in VRAM) 


A detailed description of each structure follows. 
see SMO - cartridge ROM 
The high level Gefinition, at SMO, igs composed of three 16 bit 


addresses; these are stored in the normal manner with the low order 
byte first: 


byte: 

0 address of CRAPHICS (the start of the RONed Graphics data for 
the object) 

2 address of STATUS (the object's RAM status area) 

4 address of OLD_SCREEN (VRAM or CPU RAM area for saving 


é background information; bit 185 of the OLD_SCREEN address is a 
- flag indicating whether or not Backgrounds are to be saved; if 
" bit 15 is set, backgrounds will not be Saved). 


®at CRAPHICS - cartridge ROM 


The ROMed graphics data for a Semi-Mobile object can be thought of 
conceptualy as three chunks. Each chunk is stored as follows: 


pm 
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eae Parameters and Pointers 


byte: 


- Parameters e- 


OBJ_TYPE - OBJ_TYPE is divided inte two parts: 

LEN - specifies the ebject type which, fos Semi-Mobile 
objects, wpust equal 0. 

MSN - only Beaningful when the VDP is operating in graphics 
wmode II. Bits 3, 6 and 7 indicate which third or thirds of 
the pattern plane the object (or any part of the object) may 
be required to appear. This inforwpation is used by routines 
which move the object's pattern and color generator data to 
VRAM. 

bit 7 = if set, generators will be moved to the ist third of 
the generator tables. 

bit 6 = if set, generators will be moved to the 2nd third. 

bit 5 - if set, generators will be moved to the 3rd third. 

Bit 4 - indicates the number of color generator bytes per 8 
byte pattern generator which are included as part of the ROM 
qraphics data. Tf this bit is 0, then there must be 8 color 
generator bytes per pattern generator (the normal case for 
Graphics mode II). If bit @ is 1, then only 1 color generator 
byte per pattern generator will be expected, giving the 
Programmer the option of reducing the number of ROMed color 
generator bytes needed when Operating in graphics mode II. 
The single color byte will be expanded to 8 bytes by the 
routine which moves the color generators to VRAM. 


FIRST_CEN_NAME - an index from the start of the pattern and 
color generator tables in VRAM. This index specifies the 
location to which the ROMed pattern and color generators wil! 
be moved (i.e. the base address of the pattern generator table 
+ 6 * FIRST_CEN_NAME @ the address within the pattern 
Generator table where the object's ist pattern generator will 
be stored. This is also true for the color generator table. 
The first pattern generator will be moved to the location in 
the pattern generator table indexed by FIRST_LCEN_NAME and the 
rest of the generators will be loaded sequentially. The color 
Generators are loaded in a similar fashion. 


NUMCEN - indicates how many pattern/color generator pairs are 
Gefined (stored) in the graphics data area. This is equal to 
the number of generator pairs which will be moved to the VRAM 
generator tables. 


- Pointers e- 


eddress of CENERATORS - the start of the ROMed pattern and 
color generators in the object's Graphics data area. Coler 
generators must be stored immediately after pattern 
generators; therefore, the address of the first color 
generator within the graphics data area can be computed from 
NUMCEN and CENERATORS. . 


pm 


COLECOVISION 
CRAPHICS USERS' MANUAL eee Pege 86 


$s address of FRAME_O - FRAME_O is the address at which the data 
Specifying the object's first frame is stored. AS indicated 
by the frame address, the Gata for a given frame may be stored 
in ROM (Cas part eof the @raphics data area) or it May be stored 
in CPU RAM. RAM storage of frame data allows for the 
8lgorithmiec generation of additional frames at Game on time: 
@.g.. rather than storing both a frame and {ts rotated version 
in ROM, ROM space can be Saved by storing only one frame and 
generating the rotated frame data in RAM. Also, frame data 
stored in RAM can be Gynamically modified, allowing for 
Special frame effects (e.g. color modification). 


? adéress of FRAME_1 - the address at which the data speck fying 
the object's second frame is stored. 


2neS address of FRAME_n - the object's Jast frame 


zee Frames - cartridge ROM or CPU RAM 


Since the frame pointers (FRAME_0...FRAME_n) are 16 bit addresses, the 
frame data for an object may be located anywhere in cartridge ROM or 
RAM. The format of a frame's Gata is as follows: 


Byte: 


0 Z_EITENT - specifies the width of the frame in Pattern plane 
positions, its "X_EXTENT", which wpust Be >) © and ¢s 255. Ag 
indicated by the range of values for the X_EXTENT, a frame may 
be much greater in width than can be displayed within the 
pattern plane. When a frane with a X_EXTENT which is Qreater 
than 32 is to be Gisplayed, the section actually visible will 
@epend on the specified x position (i.e. if a frame of an 
object has a X_EXTENT of 64 and the X position of the object 
is -8%32 pizels, then the right half of the frame will be 
Cisplayed on the pattern plane). This feature allows objects 
to be scrolled horisontally by creating a frame greater in 
width than the pattern Plane and then displaying the object 
with warying walves of the ZX position. 


1 Y_EXTENT - specifies the height of the frame in pattern plane 
positions, its “Y_EXTENT", which must be ) O and (se 255. As 
indicated by the range of values for the Y_EXTENT, a frane way 
Be much greater in height than can be Gispleyed within the 
pattern plane. When a frame with a Y_EXTENT which is greater 
than 24 ts to be Gisplayed, the section sctually visible will 
Gepend on the specified Y position (i.e. tf a frase of an 
object has a Y_EXITENT of 48 and the Y¥ Position of the object 
is -8%24 pixels, then the bottom half of the frame will be 


£N 
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Gisplayed on the pattern plane). This feature @llows objects 
to be scrolled vertically by creating a fraze Greater in 
height than the pattern plane and then Gisplaying the object 
with warying walues of the Y position. 


} ee for X_EXTENT ® Y_EXTENT bytes 
Following -the & and YLEXTENT is an array of, the pattern names 
(length in Bytes e X_EXTENT ® Y_EXTENT) which Specify the 
generators used to create that frame. The names ere arranged 
in row major order (i.e. the first X_EXTENT names are the 
Rames of the generators which will Be displayed in the first 
Tow of the frame, the second X_EXTENT names are the names of 
the generators which will be displayed in the second row of 
the frame, etc.)>. There must be exactly X_EXTENT by Y_UEXTENT 
names in the array. 


For Semi-Mobile objects the memes stored in the above 
described name list are “nazes" in the TI sense of the word: 
j.e., they are values Tanging from 6 to 255 that Girectly 
point to Cor “name") 2 generator location within the pattern 
generator table. 


weet Generators - cartridge ROM 


All the ROMed pattern and color generators must be Grouped together in 
&@ contiguous block (starting at Jocation GENERATORS). Each pattern 
generator must be 8 bytes long, and the nuzber of Pattern generators 
must conform to the value stored in NUMCEN: 


byte: 

0 bb, bb, bb. bb, Bb, Bb, bb, bb - the first 8 byte pattern generator 
(bb = binary graphic data) 

| bb,bb,bb,bb, bb, bb, bb, Bb - the second 6 byte pattern generator 

ete. for a total of &®NUMCEN bytes 


The color generators are stored immediately following the pattern 
generators. The format of the coler generators depends on which 
Graphics mode igs being used and whether bit 4 of OBJ_LTYPE is set or 
not. 


CRAPHICS MODE II color generator storage: 


When OBJ_TYPE bit @ « O, there must be eight color generator bytes per 
pattern generator. 


byte: 

6-7 bb, bb, bb, bb, bb, Bb, Bb, Bb = color generator bytes for ist 
pattern 

6-15 bb,6b,bb,6b,6b,bb,bb, Bb - color generator bytes for 2nd 
pattern 


etec., for a total of &*NUMCEN bytes 
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When OBJ_TYPE Bit @ s 1, there must be enly 1 ecolor generator byte per 
pattern generator. It will be Crpanded to © bytes when moved to the 
VRAM color generator table. This feature is useful if each generator 
for @ particular ebject can use the sane twe color combination for a}} 
6 lines. 


byte: ° e 
@ bb - color generator byte for ist pattern 
i Bb - color generator byte for 2nd pattern 


etc., for a total ef NUMCEN bytes. 


GRAPHICS MODE I eoteor Generator storage: , 
In Craphics Mode I the pattern generator table is Givided inte 32 
“groups” of 8 (contiguous) generators (see TI VDP manual page 18). 

All the generators within a @rtoup share the same color generator byte. 
Therefore, there must be one color generator Byte stored per group 
eccupied by the object's pattern generators. The first eolor 
generator byte will Be placed in the color generator table at an 
offset of FIRST_CEN_NAME/8 and the rest will be placed in Seqvential 
locations. 2 


the generators will be moved. For example, if an object has 8 pattern 
generators and they are moved to the pattern generator table starting 
at location © (offset fron the start of the table), then only 1 color 
generator is needed. However, if the same 8 Pattern generators are 
loaded into the pattern generator table starting at location 20H, then 
2 color generators will be needed, since the first four generators ere 
in one group and the second four are in another Group. 


NOTE 2: Due to an errer in the ACTIVATE routine, ACTIVATE cannot be 
used to move pattern and color generators of Seni-Mobile objects to 
VRAM when the VDP is Operating in graphics mode T, and when 
FIRST_CEN_NAME is equal to or greater than 80k. In this situation the 
cartridge program must fulfill the functions of ACTIVATE (see 
Ciscussion of ACTIVATE). 


See STATUS - CPU RAM 

An object's status Sres consists of @ elements: 

byte: © : 

6 I byte for FRAME - indicates which of the object's frames is 


te be displayed. 


1 2 bytes for X_LOCATION 
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3 2 bytes for Y_LOCATION - X_LOCATION and Y_LOCATION give the 
coordinate position ef the Upper left corner of the Object on 
a “metaplane" which includes the pattern plane (see fig. 1). 
The origin ef the pattern plane is coincident with the origin 
of the metaplane. The values at X_LOCATION and Y_LOCATION are 
16 bit signed numbers Which Perwit the positioning of an 
ebject anywhere within, or outside of, the pattern plane. 
This enables an object to be bled on er off the pattern plane 
in any direction. 


$ 1 Byte for NEXT_CEN - an index which points to the nest 
generator location which can be used when adding new \ 
generators to an object's generator tables. After the 
object's ROMed generators have been moved to its VRAM tables, 
ACTIVATE will set NEXT_CEN equal to FIRST_CEN_NAME « NUMCEN. 


Some objects may require generators which are essentially 
modified versions of other generators (e.g. a generator which 
represents the pattern of another generator which has been 
rotated). ROM space can be Conserved by including only the 
"unmodified" generators in the graphics data and using system 
routines to generate the modified versions. NEXT_CEN points 
to the next free location in that object's generator table to 
which a modified generator may be added. When adding new 
generators in this manner, NEXT_GEN should be updated in order 
to prevent new generators Overwriting old ones. 


*e® OLD_SCREEN - VRAM or CPU RAM 


OLD_SCREEN is a buffer for Saving the pattern names which are 
Overwritten in the process of Gisplaying an object. These names 
constitute a “background frane" which has the same X and Y_EXTENTs as 
the frame of the object which is Currently being displayed. The Gata 
structure within OLD_SCREEN is the same as the data structure for a 
frame with two ertra bytes tacked on at the beginning. These bytes, 
Z7_PAT_POS and Y_PAT_POS, indicate where on the pattern plane this 
background frame belongs, and are expressed in terms of pattern plane 
positions. The next time the Position or frame of this object is 
changed PUT_OBJECT will restore the background frame to the display 
and save a “new" background frame before Placing the object on the 
pattern plane. 


byte: 
6 * 1 Byte for X_PAT_POS - the column in which the upper left 
- Corner of the saved background screen (frame) lies 


| ' 1 byte for Y_PAT_POS - the row in which the Upper left corner 
of the saved background screen (frame) lies 

2 l byte for X_EXTENT of the saved screen - set by PUT_OBJECT to 
equal X_EXTENT of the frame which eclipses it 

3 1 byte for Y_EXTENT of the saved Screen - set by PUT_OBJECT to 
equal Y_EXTENT of the frame which eclipses it 

4 n bytes for storage of pattern names; where n = the nunber of 
patterns contained in the largest frame of the objyect (i.e. an 


* XLEXTENT * Y_EXTENT for the object's largest frame) 
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3.0 MOBILE OBJECTS 


Mobile objects emulate sise 1 sprites with © magnification (i.e. they 
are always 16 ‘by 16 pisels in sise and eppear as if they were 
superimposed upon the background). They may be positioned anywhere on 
the pattern plane with Pixel resolution and may also be made to bleed 
on and off the pattern plane in any direction. 

Each frame of a Mobile ebject requires exactly four “pattern generators 
and one color generator. These generators, however, are not moved to 
VRAM. In order to Gisplay the object anywhere with pizel resolution, 
& new set of nine pattern and eolor Generators must be created by the 
OS graphics routine PUT_MOBILE. These new Generators represent 
Graphically the superposition of the Mobile object upon the background 
at which it ‘is to be Gisplayed. The new generators are then moved to 
the VRAM pattern and eolor generator tables, and next the nazes of 
these generators are written into the pattern name table, thus 
Cisplaying the object at the desired location. Nine generators are 
used in order to cover all positional relationships between the 
desired position of the object and the boundries of the pattern 
positions in the pattern plane (see figure 1). 


The pattern and color generator table space used by PUT_MOBILE depends 
on the graphics mode being used and, in Graphics wmode JI, the location 
of the object on the Gisplay. 


In graphics mode I, PUT_MOBILE will use 128 pattern generator 
locations. The first pattern generator will be located at 
FIRST_GEN_NAME (i.e. the actual VRAM address will be the pattern 
generator Base address ¢ FIRST_CEN_NAME ® 8). Three or four color 
generator bytes will be required CGepending on the value ef 
FIRST_CEN_NAME. If FIRST_CEN_NAME MOD 8 ¢ 7, then there needs to be 
space for three color generators: if FIRST_GEN_NAME MOD 8 «= 7, then 
there needs to be space for four color generators. The first of the 
color generators will be located at FIRST_GEN_NAME/8 (i.e. VRAM 
address equals the color table base address « FIRST_CEN_NAME/8). 


When operating in Graphics mode II, Mobile objects will require 
Generator space for 18 pattern and 18 eolor generators in each third 
of the pattern and coler Generator tables which Corresponds to that 
third of the pattern plane in which any part of the object may appear. 
The Jocation within each third of the tables is determined by 
FIRST_CEN_NAME. When any part of the object is in the top third of 
the pattern plane, pattern generators will be located at the VRAM 
address given by the pattern generator base address ¢ FIRST_CEN_NAME 8 
B. If, any part is in the middle third of the pattern plane, pattern 
generators will be located at the VRAM address given by the pattern 
Generator base address ¢ B800H ¢ FIRST_CEN_NAME ® 8, and if any part is 
in the bottom third, pattern generators will be located at the VRAM 
address given by the pattern generator base address ¢ 1000H ¢ 
FIRST_CEN_NAME ® 8. The color generators are located in a similar 
manner. ° 
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Even though only 9 pattern and 9 color generators (2 color generator 
bytes in graphics mode I) are “active" (being displayed) at a given 
time, the additional generator space is required to enable PUT_MOBILE 
to move new sets of pattern and color generators to VRAM without 
Gisturbing the display. While one set of 9 pattern ané coler 
generators are being displayed, the other set of 9 can be changed. 
After the change is completed,’ the new generators ate Gisplayed by 
writing the new pattern names into the pattern name table. 


Each Mobile object requires a STATUS area in CPU RAM which contains 
the frame of the object to be Gisplayed, its lecation on the Gisplay, 
and @ pointer to the area for adding new generators (these new, 
generators ere used in the same manner as the obsect's ROMed 
generators). Each object also requires an OLD_SCREEN area which 
serves the same purpose as OLD_SCREEN areas for Semi-Mobile objects. 


Even though a Mobile object's generators are not moved directly to 
VRAM, each object must be “activated” in order to initialise the 
OLD_SCREEN and STATUS areas. 


To place a Mobile object on the display, the desired bocation should 
be loaded into the X and Y_LOCATION wariables in its STATUS area. In 
addition, the FRAME wariable must contain the desired frame number. 
When loading the frame number, however, only bits 0-6 should be used. 
Bit 7 should not be altered. This bit is used By PUT_MOBILE (see 
Gescription of PUT_MOBILE). 


PUT_OBJECT is then called, passing the address of the high-level 
Gefinition in the IX register. In addition, register B is used to 
pass two parameters which determine the method for combining the 
background graphics with that of the object (see description of 
PUT_MOEBILE). 


$3.1 DETAILED DESCRIPTION OF MOBILE OBJECT 
DATA STRUCTURE 


(Identifiers in caps refer to symbols in the data structure Summary) 


Each Mobile object is defined in cartridge ROM by: 
1) MOB - the object's “high level definition" 
2) CRAPHICS - an area containing the object's graphic data, divided 
into three subsections: 
Parameters and peinters 
Franses 
Generators 


and in CPU RAM by: 

1> STATUS - a status area 

2) OLD_SCREEN - a location for saving everwritten background names 
COLD_SCREEN may be either in CPU RAM or VRAM). 


A detailed description of each structure follows. 
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eee MOB - cartridge ROM 


The high level definition at MOB is Composed of four 16 bit addresses 
stored in the normal manner with the low order byte first: 


byte: . 

e address ef CRAPHICS (the start of the ROMed graphics data for 
the object). Any number of Mobile objects may use the sane 
eraphies data. However, each Mobile object must have its own 
STATUS and OLD_SCREEN areas. 

2 address of STATUS (the object's RAM status area) 

4 address of OLD_SCREEN (VRAM or CPU RAM area for saving 
background information) \ 

é FIRST_CEN_NAME (Cinder to the start of the object's generator 


tables within the VRAM pattern and color generator tables) 
Ben GRAPHICS - eartridge ROM 


The ROMed graphics for Mobile objects may be thought of as three 
Separate segments. The data in each Segment is defined as follows: 


eee Parazeters and Pointers 


byte: 
- Parameters - 
OBJ_LTYPE - for Mobile objects OBJ_TYPE e@ 1 

1 NUMCEN - indicates how Many pattern generators are contained 
within the graphics data area. 

2 address of NEW_GCEN (an area for storing new generators created 
at game-on time) 

4 address of GENERATORS - the start of the ROMed pattern 
generators for the object 
- Pointers - 

é address of FRAME_O - this is the address of the start of the 
Gata for the object's first frame. This data, as well as the 
Gata for any of the object's frames, may be located anywhere 
in cartridge ROM or in CPU RAM. Frame data stored in RAM 
allows for the creation of new frames at game-on time and 
therefore reduces the amount of Gata which needs to be stored 
es part ef the object's ROMed fraze Gata. 

8 acdress of FRAME_1 - address of the Gata for the object's 

° second frame. 
2neé address of FRAME_n - the ebject's frame. 
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ase Frames - each frame may be either in cartridge ROM or CPU RAM 
FRAME_0...FRAME_n - cartridge ROM or CPU RAM 


Since the frame pointers (FRAME_0...FRAME_n) are 16 Bit eddresses, the 
frame data for an object may be located anywhere in cartridge ROM or 
CPU RAM. The format for a Mobile object's frame data if a8 follows: 


Byte: 

0 list of @ pattern names. The four names specify which of the 
object's patterns are to be displayed in each of the object's 
four quadrants as follows: 


neme quadrant 

i upper left 

2 lower left 

3 upper right 

4 lower right 
The value of the name specifies the object's generators as 
follows: 


@ = first ROMed pattern 
1 s second ROMed pattern 


NUMCEN-1 = last ROMed pattern 
Name values greater than or equal to NUMGEN refer to patterns 
stored in the location starting at NEW_GEN in CPU RAM. A 
value of NUMCEN refers to the first pattern in that area. A 
value of NUMCEN + 1 refers to the second pattern etc. 

4 The MSN of this byte determines the color of the object (i.e. 
the colori of the object) and the LSN must be 0. 


weak Cenerators - cartridge ROM 


All of a Mobile object's pattern generators must be grocped together 
in a contiguous block starting at location CENERATORS. Each pattern 
generator must be 8 bytes long. The number of generators must equal 
the number stored in NUMGEN: 


byte: 

6 bb,bb,bb,bb,bb,bb,bb,bb - first generator (bb = binary graphic 
Gata) 

8 bb,bb,bb,bb,.bb,bb,bb,bb - second generator 


for a total of &B*NUMCEN bytes 
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a8 STATUS - CPU RAM 


A Mobile object's status area consists of 4 elements 


byte: 

0 FRAME - bits 0-6 indicate which frame is to be Gisplayed. Bit 
7 is used-by the PUT_MOBILE routine and should not be altered 
when changing the fraze Number. 

1 X_LOCATION 

3 Y_LOCATION - The xX and Y_LOCATION vwariables specify the 
coordinate position of the Upper left corner of the object on 
a “petaplane" which includes the pattern plane. 

5 pointer to NEW_GEN area - This pointer points to the nert 
available space for adding new generators. Tt will be 
initialized by ACTIVATE with the 16 bit value NEW_CEN from the 
Parameter segment of the object's CRAPHICS area. Routines 


which add generators to this area should increment the pointer 
by 8 each time a new generator is added if subsequent 
generators are not to overwrite Previous ones. 


aex® OLD_SCREEN - VRAM or CPU RAM 


OLD_SCREEN is an area for Saving pattern names which are overwritten 
in the process of Gisplaying the object. Since all Mobile objects are 
Cisplayed by writing 9 mames into the patten name table Cexcept in 
cases in which part of the object is off the pattern plane) the size 
of the OLD_SCREEN area for any Mobile object is always 11 bytes. The 
first two bytes Specify where (in pattern Plane positions) the names 
came from and the next 9 bytes contain the 9 saved names. ACTIVATE 
initialises the first byte to 80H which indicates to PUT_MOBILE that 
no names have yet been saved. 


byte: 

0 I_PAT_POS - pattern Position column in which the upper left 
Corner of the saved “background frame" lies 

1 Y_PAT_POS - pattern Position row in which the upper left 


corner lies 
2-11 the nine background names 
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4.06 SPRITE OBJECTS 


Eprite objects are Composed of individual Sprites. They may be either 
sizeO or siseil sprites, and Mey or may not be magnified. 


The data areas that make Up sprite objects are similar to those for 
the other object types. The high level definition contains two 
addresses which point to the object's GRAPHICS data and the STATUS 
area respectively. Following these addresses there is a byte which 
determines which of the 32 VDP Sprites will be used to implement this 
object. 


Each Sprite object must include a set of pattern generators which will 
be used to create an image on the Gisplay. These generators may be 
stored as part of the object's GRAPHICS data in ROM and moved to the 
Sprite generator table in VRAM. The lIecation within the sprite 
Generator table to which the generators should be moved is determined 
by FIRST_CEN_NAME, a byte within the GRAPHICS data area (i.e. the 
first generator should be located at VRAM address « Sprite generator 
base address ¢ FIRST_CEN_NAME ® 8). 


Franes for a Sprite object are defined in the FRAME_TABLE. The 
FRAME_TABLE contains a pair of bytes for each frame of the object. 
The first byte specifies the color “that the frame will be and the 
second byte determines which generator Cor generators in the case of 
Sizeil sprites) will be used to define the shape. 


Once the pattern generators have been moved to VRAM, a Sprite object 
may be displayed by setting up it's STATUS area and then calling 
PUT_OBJECT. To set up the STATUS area, the following must be done: 


1. Set the first byte, FRAME, to the Gesired frame number to be 
Gisplayed. This number is used to pick one of the pairs of 
bytes in the FRAME_TAELE which determines the color and shape 
to be displayed. 


2. The 16 bit signed vwalves at X_LOCATION and Y_LOCATION must be 
set to the desired x and y pixel positions of the upper left 
Corner of the object. 


To place the Sprite object on the screen, the following calling 
Sequence is used: 


ID IX ,OBJECT_NAME 
° CALL PUT_OBJECT 


Where OBJECT_NAME is the address of the high level definition for the 
object. 
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€.1 DETAILED DESCRIPTION OF SPRITE OBJECT 
DATA STRUCTURE 


(Identifiers in eaps refer to Symbols in the data structure Summary) 


Each Sprite object is defined in cartridge ROM by: 
1) SPROBJ - the object's “high level definition" 
2) GRAPHICS - an area containing the object's graphics data, divided 
inte three subsections: 
Parameters and Pointers 
Frane_ Table 
Cenerators 


and in CPU RAM by: 
1> STATUS - a status area 


A detailed description of each structure follows. 

ees SPROBJ cartridge ROM 

The high level definition, at SPROBJ, is composed of two 16 bit 
addresses stored in the normal manner with the low order byte first. 


Following the addresses is a byte which indicates which actual sprite 
number is used to implement the object. 


byte: 

6 address of GRAPHICS (the start of the ROMed Graphics data for 
the object) 

2 address of STATUS (the object's RAM status area) 

4 SPRITE_LINDEX (determines the sprite to be used for this 


ebject, i.e. 0-31) 
mae GRAPHICS - cartridge ROM 


The ROMed graphics data fora Sprite object can be thought of in three 
conceptual chunks. Each chunk is stored as follows: 


gee Parameters and Pointers 


byte: 
6 OBJ_TYPE - OBJ_TYPE is equal to 3 for al! Sprite objects. 
i FIRST_CEN_NAME - an index into the sprite pattern generator 


table in VRAM. This index specifies the location to which the 
ROMed pattern generators will be moved (i.e. the base address 
of the sprite pattern generator table « @ ® FIRST_CEN_NAME «& 
the address within the pattern generator table where the 
object‘’s ist pattern generator will be stored). The first 
pattern generator will be moved to the Jocation in the pattern 
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Generator table indexed by FIRST_GEN_NAME and the rest of the 
Generators will be loaded Sequentially. When using size: 
Sprites, FIRST_GEN_NAME must be a wpultiple of 4. 


2 address of CENERATORS - the start of the ROMed pattern 
Generators in the object's Graphics data area. 


4 NUMCEN - indicates how Many pattern generators are defined 
(stored) in the graphics data area. This is the number of 
generators which will be moved to the VRAM generator table. 


$ address of FRAME_TABLE - This is a pointer to the table 
containing shape and color information for each frame of the 
object. 


eee FRAME_TABLE - cartridge ROM or CPU RAM 


The FRAME_TABLE contains a pair of bytes for each frame. The first 
byte of each pair determines the color and the second.byte points to 
the generator (or set of four generators in the case of sizel Sprites) 
to be used for that frame. 


byte: 

0 COLOR for frame 0 

1 SHAPE - index to generator(s) for frame 0, e.g. the VRAM 
address of the generator(s) for this frame «= sprite generator 
base address + 6 ® CFIRST_GEN_NAME ¢ SHAPE). When using sizei 
sprites, the value of SHAPE must be a multiple of 4. 

2 COLOR for frame 1 

3 SHAPE for frame i 

2n COLOR for frame n 

z2nel SHAPE for frame n 


&ae CENERATORS - cartridge ROM 


All the ROMed pattern generators must be grouped together in «a 
contiguous Block (starting at location CENERATORS). Each pattern 
generator must be 8 bytes long, and the number ef pattern generators 
must conform to the value stored in NUMCEN: 


e 


byte: . 

6 bb,bb,bb, bb, bb, bb, bb, Bb - the first 8 byte pattern generator 
(bb = binary graphic data) 

| bb,bb,tb,bb,bb, bb, Bb, bb - the second 8&8 byte pattern generator 


ete. for a total of &8*NUMCEN bytes 
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eax STATUS - CPU RAM 


An object's status srea consists of 4 elements: 


Byte: 


1 byte for FRAME - indicates which of the object's frames is 
to be displayed. 


2 bytes for X_LOCATION 


2 bytes for Y_LOCATION - X_LOCATION and Y_LOCATION give the 
coordinate position of the upper left corner of the object on 
a “metaplane” which includes the pattern plane (see fig. 1). 
The origin of the pattern plane is coincident with the Origin 
of the metaplane. The values at X_LOCATION and Y_LOCATION are 
16 bit signed numbers which permits the positoning of an 
object anywhere within or outside of the pattern plane. This 
enables an ebject to be bled on er off the pattern plane in 
any direction. 


1 byte for NEXT_CEN - an index which points to the nert 
generator location which can be used when adding new 
generators to an object's generator tables. After the 
object's ROMed generators have been moved to its VRAM tables, 
ACTIVATE will set NEXT_GEN to equal FIRST_GEN_NAME « NUMCEN. 


Some objects may require generators which are essentially 
modified versions of other generators (e.g. &@ generator which 
represents the pattern of another generator which has been 
rotated). ROM space can be conserved by including only the 
“unmodified" generators in the Graphics data and using systen 
routines to generate the modified versions. NEXT_CEN points 
to the next free lIocation in that object's generator table to 
which a modified generator may be added. When adding new 
generators in this manner, NEXT_CEN should be updated in order 
to prevent new generators overwriting old ones. 


COLECOVISION 
GRAPHICS USERS’ MANUAL Page 21 


5S .0 COMPLEX OBJECTS 


Complex objects are aggregates of other “component” objects which may 
be of any type Cincluding ether Complex objects) except Mobile 
objects. This object type gives the game programmer the ability to 
combine several objects in order to create a higher order graphic 
entity. Complex objects may have multiple frames and may be moved 
about on the display in the sawe manner as any other object. 


Before a Complex object can be Gisplayed, all of its component objects 
must be activated. This can be done by activating the complex object 
itself CACTIVATE will then process a1) the component objects). 
However, if any of the component objects are type Semi-Mobile and the 
VDP is operating in graphics mode I, then all the component objects 
must be individually actiwated. If ACTIVATE is not used, then in 
addition to moving the generators to VRAM, the FRAME variable in the 
STATUS area for each of the component objects must be initialized to 
0G. 


Once 211 the component objects are activated, a Complex object may be 
placed on the display in the same manner as any other object type. 
The object's STATUS area is initialised with the desired frame number 
and position, and then PUT_OBJECT is called. PUT_LOBJECT will then 
determine the correct frame number and position for all of the 
component objects and place them on the Gisplay. 


Each frame of the Complex object points to a list of frame numbers and 
alist of offsets. The list of frame numbers specifies the frame 
mumber to be used for each of the Component objects. The list of 
offsets specifies the positional! offset of each of the component 
ebjects from the Complex object's X and Y_LOCATIONs. 


5s .1 DETAILED DESCRIPTION OF COMPLEX OBJECT 
DATA STRUCTURE 


Complex objects are defined in cartridge ROM by: 

i) COM_OB - the object's high level éefinition 

2) GRAPHICS - which contains frane and offset parameters. For each 
frame of the Complex object, these parameters define the frame numbers 
for the component objects and the positional relationship between the 
component objects. 


ané in CPU rape by: 
1) STATUS - which contains the frame and position variables for the 
object. 


The following is a detailed description of the data structtre: 


COLECOVISION 
GRAPHICS USERS’ MANUAL page 22 


2&2 COM_OB - cartridge ROM 
The high level! Gefinition of ¢ Comples object contains pointers to the 


GRAPHICS ang STATUS areas for the object, ané a list ef addresses 
Peintiag to the high leve) Gefinition of the component objects. 


byte 

6 address ef GRAPHICS (the start of the ROMed graphics data for 
: the object) 

2 address ef STATUS (the ebject's Ran Status area) 

4 acdcress of the Ist Component object high level definiton 

é « e eo 2nd o a e a o 

2n42 s s a ath . co] e ee Ld 


®e2 CRAPHICS ~ Cartridge RON 


The Gréphics seguent of a Complez ebject can be thooght ef ag divided 
into three Sections. The first Section contains the following: 


byte: 
0 OBJ_TYPE ~ This byte is ¢ivided into two parts: 
LSN - specifies the object type and must be equal to @ for 
Coaplex objects. 
MSN - contains the number of Component ebjects that Bake ep 
the compler object. 
P| Pointer to FRAME_O (list ef frame numbers) 
3 Pointer to OFFSET_O (list of offsets) 
5 Pointer to FRAME_1 
? Pointer to OFFSET 1 


2ne1 Pointer to FRAME_n 
2042 Poiater to OFFSET_» 


fe! FRAME_O ... FRAME_n - cartridge ROM or CPy RAM 


Each frame of a Complex object Specifies the frame Bumbers to be used 
for each of its Component objects. The frame numbers to be used for 
aty giten frane are arranged in ¢@ list; the first entry Being the 
frame nurber for the first Component, the second entry the frame 
nenber for the Sencond component, etc. There Bay be as many frame 
lists es there are frames, or Several or all frames Biy share the sane 
frame list. for @xanple, if the only difference between frames ef a 
Compler object were the positional! relationship of the component 
Objects, then one frame list would be sufficient. The format of the 
fraze hist is as follows: 


byte: . 
0 frame number for ist Component 
1 = = “ i3né - 


Rel . = "* ath 
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#22 OFFSET O ... OFFSET» - Cartridge ROM or CPU RAM 


Each entry in the offset list has two Components, a one byte £ 
Cisplacement followed by a one byte Y¥ Gisplacement. These 
Cisplacements are unsigned 8 bit integers and are added to the 16 bit 
values contained in the Complex object's x and Y_LOCATIONs to form the 
coordinate position for each of the component objects. As with the 
frame lists, there Bay be as many offset lists as there are frames, or 


byte: 

0 I displacement for the ist component ebject 

1 Y e we e {st J s 

2 z = » " ind © = 

3 Y ° _ " and " - 

2n I e e a ath & oe 

2ae1 Y - * "= ath sa . : 


wan STATUS - CPU RAM 


The STATUS area for a Complex object is similar to the STATUS area for 
any other object type. The only difference is that the Sth byte, 
‘ETLGEN, is not used. 


byte: 

0 FRAME - the value in this byte indicates the frame to be 
Cisplayed. 

1 Z_LLOCATION - a two byte valce Cetermining the x Position of 
the Complex object on the display. ; 

3 Y_LOCATION - a two byte valve determining the Y Position ef 


the Complez object on the display. 
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6.0 ACTIVATE 


Calling sequence: 


LD HL ,OBJECT_NAME 
SCF + MOVES GENERATORS To VRAM 
CALL ACTIVATE 


-Ore 


LD HL, OBJECT_NAME 
OR A + DOESN'T MOVE CENERATORS TO VaRN 
CALL ACTIVATE 


Registers used: 
Uses all tTegisters 
RAM Used (starting at WORK_BUFFER): 


If the object type is Semi_Mobile, the VDP is Operating in Graphics 
Mode IJ, and bit 4 of OBJ_TYPE « 1, then 8 bytes starting at 
WORK_EBUFFER are used. Otherwise no RAM is used. 


6.1 DESCRIPTION OF ACTIVATE ROUTINE 


The Primary purpose of the ACTIVATE routine is to move the pattern and 
color generators from an object's CRAPHICS data area to the locations 
in the VRAM pattern and color generator tables @essigned to it. In 
addition ACTIVATE will initialize certain variables in the object's 
STATUS and OLD_SCREEN areas. How the routine actually functions is 
Cependent on the type of object being "activated", the Graphics mode 
being used, and the state of the Carry flag. 


1) Activating Semi-Mobile objects 


If the thira address pointer in the object's high level Gefinition is 
less than BOOCOH, then that address is taken to be the address of an 
OLD_SCREEN area for that object. The first byte in the OLD_SCREEN 
area is initialized with an 80H. This value indicates that no Gate 
has yet been Saved in OLD_SCREEN. When PUT_OBJECT Sees this value it 
will not attempt to restore the contents eof OLD_SCREEN to the display. 


The first byte in the object's STATUS area, the FRAME variable, is set 
to 6. ; 
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The 6th byte in the object's STATUS area will be initialized with ea 
valve equal to FIRST_CEN_NAME ¢ NUMCEN. Routines which acd new 
generators to the object's pattern and color generator tables may 
access this byte to determine where to put then. 


If the Carry flag is set when ACTIVATE is called, then the object's 
Pattern and Color generators will be moved to the Pattern and color 
generator tables in VRAM. If the carry flag is not set, then the 
Generators will not be moved; in this case only the STATUS and 
OLD_SCREEN areas will be affected. This feature is used when several} 
ebjects share the sane Generators. ACTIVATE needs to be called with 
the carry flag set for only one of the objects, to get the generators 
to VRAM, and the other objects are ACTIVATE with the carry flag not 
set to prevent the Generators from being moved again. The generators 
are moved as follows: 


a) In Graphics Mode 1} 
All the pattern generators (the number of which is given by the 
NUMGEN entry) are moved to the pattern generator table in VRAM. 
The first generator is moved to a location within the table 
Specified by FIRST_CEN_NAME (i.e. the VRAM address to which the 
first pattern generator is moved «x pattern generator base address 
+ 8 * FIRST_GEN_NAME). The others are loaded Sequentially. 


In Graphics Mode I the pattern generator table is CGivided into 32 
eight-byte blocks. The color for each block of 8 generators is 
defined by one color Generator byte. Therefore, ACTIVATE needs 
to determine the number ef color generator bytes that must be 
moved to the VRAM color generator table. It does this in the 
following manner (see NOTE below): 


The first pattern Generator will require a color generator byte 
at FIRST_CEN_NAME/8& offset from the start of the color generator 
table. The last pattern generator wil] require a color generator 
byte at CFIRST_GEN_NAME «+ NUMGEN -1)/8. Therefore, the total 
mumber of color generators needed will be CFIRST_CEN_NAME ¢ 
NUMCEN -1)7/8 - FIRST_CEN_NAME/8 41. ACTIVATE will move this 


b) In Graphics Mode I] 
In this mode the pattern and color generator tables are divided 


into three sections. Each section contains the generators which 
"will be Cisplayed in the Corresponding third of the pattern 
plane. A Semi-Mobile object needs to have it's generators moved 


to ene or more sections Gepending on which thirds of the pattern 
Plane it may @ppear in. The MSN of OBJ_TYPE in the object's 
CRAPHICS data area indicates which sections of the generator 
tables the pattern and color generators should be moved to as 
follows: 
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if bit 7 = j then move generators to the ist section 
if bit 6 = 1 then move generators to the 2nd section 
if bit S = 1 then move Generators to the 3rd section 
The starting location within each section to which the generators 
Will be moved is specified by FIRST_GEN_NAME. The first 
pattern/coler generator will be located at FIRST_CEN_NAME and the 
rest will be loaded Sequentially (e.g. if the MSN of &@ Semi- 
Mobile object = 10108, then the pattern generators will be moveg 
to VRAM address «= pattern base address ¢ FIRST_GEN_NAME * 8, ang 
also to VRAM address e pattern base address ¢ 1O00H ¢ 
FIRST_CEN_NAME ® 68). 


Bit @ of OBJ_TYPE indicates whether there are 8 or 1 color 
Generator bytes per pattern generator. If this bit is 0, then 
ACTIVATE will expect 8 color generator bytes per pattern 
generator. If bit @ is 1, then only one color generator byte 
will be expected. This Byte will be used to fill all eight bytes 
of the appropriate color generator in VRAM. The location within 
the color table to which the generators are woved is determined 
in the same fashion as the pattern generators (See above). 


2) Activating Mobile objects 


The first byte of the object's OLD_SCREEN area is initialized with 
80H. 


The frame variable, the first byte in the object's STATUS area, is 
initialized to 0. 


Bytes 6 and 7? of the object's STATUS area are initialized with the 
value NEW GEN from the object's CRAPHICS data. This value is used as 
@ pointer to the beginning of an area reserved for the addition of 
Generators created at G&ame-on time. 


3) Activating Sprite objects 


The frame variable, the first Byte in the object's STATUS area, is 
initialised te o. 


Byte 6 of the object's STATUS area is initialised with the value 
FIRST_CEN_NAME ¢ NUMCEN. 


All the generators in the GRAPHICS data area are moved to the Sprite 
Generator table in VRAM. The first generator is moved to the location 
Specified by FIRST_CEN_NAME and the rest are loaded in Sequentially. 


@) Activating Compler objects 
The number of Component objects to activate is Getermined by the value 


Contained in the MSN of OBJ_TYPE, the first byte in the object's 
CRAPHICS gata area. Following the pointer to the object's STATUS area 
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is a list of addresses. Each address in the list points to the high 
level definition for one of the Component objects. ACTIVATE {8 called 
Once for each-of the Component objects, with the state of the Carry 
flag set to the Condition it was in when the routine was initially 
called. 


NOTE: : . 
An error in the ACTIVATE routine shows up when ACTIVATEing Semi-Mobile 
objects, or Complex objects containing Seni-Mobile objects, and the 
VDP is Operating in Craphics Mode I. This error causes an incorrect 
number of color Generator bytes to be moved to the color table in VRAM 
when FIRST_GEN_NAME of the object is 80H or greater. In these 
instances, the cartridge program will have to fulfill the functions of 
ACTIVATE, and move the pattern and Color generators to VRAM itself. 
Initialization of the STATUS and OLD_SCREEN reas can still be done by 
ACTIVATE; make Sure the carry flag is NOT set when calling ACTIVATE on 
such objects. 
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7.0 PUT_OBYJECT 


Calling sequence (for ell object types @xcept Mobile objects): 


LD 1X,O0BJECT_NAME 
CALL PUT_OBJECT 


Registers used: 
Uses a11 registers 
RAM used (starting at WORK_BUFFER): 


1. Semi_Mobile 
If OLD_SCREEN is not used, then no RAM area is used by 
PUT_LOBJECT. If OLD_SCREEN is used, then the marinun Space, in 
bytes, used by PUT_LOBJECT wil! be equal to the number of 
pattern blocks in the Jargest frame (i.e. the largest value of 
Z_LEITENT ® Y_EXTENT) Plus 4. 


2. Mobile 
See discussion of PUT_MOBILE below. 


3. Sprite 
4 bytes. 


4. Compler 
The amount of RAM used is equal to the largest amount used By 
any of its component objects. 


ae | DESCRIPTION OF PUT_LOEJECT 


PUT_LOBJECT places a frame of an object on the display. Which frame is 
Cisplayed and where it is placed on the Gisplay are specified in that 
object's STATUS area. When PUT_LOBJECT is called, it will determine 
what type of object is to be “put” on the Cisplay and then branch to 
one of four subroutines Gesigned to handle that particular object 
type. These subroutines are: PUT_SEMI, PUT_MOBILE, PUT_SPRITE and 
PUT_COMPLEX. Below is a Cescription of each routine. 


7? .2 DESCRIPTION OF PUT_SEMI 


As the name implies, this routine handles the Gisplay of Semi-Mobile 
Objects. A frame for a Semi-Mobile object is put on the Cisplay by 
writing the list of generator names that define the frame into the 
pattern name table in VRAM. In addition, the names in the name table 
that are overwritten may optionally be saved and later restored to the 
Hame table when the object is moved, or Temoved from the Gisplay. 
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The following algorithms is used to Place Bemi-Mobile objects on the 
Gisplay: 


IF the object does NOT have an OLD_SCREEN (i.e. if bit 185 of 
the OLD_SCREEN address in the object's high level definition 
is set), THEN 


DISPLAY the frame indicated by FRAME in STATUS at location 
specified by X_LOCATION and Y_LOCATION 


ELSE 


IF ist BYTE of OLD_SCREEN is NOT 80H (there is walid data 
in OLD_SCREEN), THEN 


DISPLAY OLD_SCREEN, first 2 bytes in OLD_SCREEN give xX 

and Y coordinates of upper-left corner Cin pattern 

plane positions) of OLD_SCREEN frame, third and 

fourth bytes give X and Y_EXTENTs of OLD_SCREEN frame 
READ Background pattern names over which frame of object 


will be displayed and save in OLD_SCREEN along with X and 
Y positions and X and Y_EXTENTS 


DISPLAY new frame of object at called for X and Y position 


ENDIF 


7.3 PUT_MOBILE 


Calling sequence: 


LD 1X%,O0BJECT_NAME 


LD 8,MODE i MODE @» 0-3, DETERMINES THE METHOD 
i FOR COMBINING BACKGROUND AND OBJECT 


CALL PUT_MOBILE + PUT_MOBILE ENTRY IS IN CARTRIDGE ROM 
; + (SEE DISCUSSION BELOW) 


Registers used: 
Uses all registers 


RAM Used (starting at WORK_BUFFER): 
In graphics mode I, 141 bytes 
In graphics mode I1, 203 bytes 
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7.4 DESCRIPTION OF PUT_MOBILE 


This routine will place the specified frame of a Mobile object on the 
display. The location of the object and the frame to be displayed are 
Getermined by the variables FRAME, ZX_LOCATION and Y_LOCATION in its 
STATUS area. The X and Y_LOCATION variables specify the pizel 
position of the upper left corner of the object on the meta-plane. 

The object therefore may Gisplayed as entirely on the pattern plane or 
ss bleeding on or off the pattern plane in any Oirection. 


In general, PUT_MOBILE produces the image of a Mobile object on the 
Gisplay by creating a new set of pattern and color generators which 
Gepict the object superimposed on the background. Since all frames of 
Mobile objects will be 2 by 2 pattern blocks in Sise, the number of 
new generators which need to be created is 9. These 9? generators 
constitute a “surround” for the object within which the object will be 
displayed. 


The 9 pattern generators which constitute the Surround may be thought 
of as an array of 3 by 24 “surround" bytes. Similarly, the pattern 
generators which constitute the frame of the object to be displayed 
may be thought of as an array of 2 by 16 "frame" bytes. PUT_MOBILE 
uses one of two methods for combining these two arrays of generator 
bytes. Which method is used is selected by the state of bit 0 in 
register B when PUT_OBJECT is called. 


If this bit is sero then an “additive” method is used to combine the 
object's graphics with that of the surround. In this method the "1" 
bits in the object's pattern generators are "moved" into the 
appropriate locations in a new set of surround generator bytes; these 
Create a graphic of the Mobile object Superimposed on the background. 
New surround color generator bytes are created as follows: 


For each byte, if the corresponding pattern generator byte has not 
been changed (i.e. no “1" bits have been moved to it) then that 
color Byte is left alone. If the corresponding pattern generator 
byte has had one or more “i" bits added to it, then the coleri 
portion of that byte is changed to the color of the Mobile object. 
Therefore, any parts of the Background graphic represented by "i" 
bits will take on the color of the Mobile object when both the 
background and the object have “1" bits within the same pattern 
generator byte. The overall effect of this method is to waintain 
the “structural” integrity of the background pattern, even though 
the color of the background graphic will change to that of the 
ebject whenever elements of the object and the background exist 
within the same generator byte. Figure 2 illustrates the graphic 
effect of this mode of operation. 


If bit © of register B is set to 1, then another method is applied. 
As in the above method, the “i" bits of the object's pattern generator 
bytes are again moved to the appropriate locations within the new set 
of surround generator bytes. However, surround generator bytes to 
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which Bits are to be added will be cleared first (i.e. any elements 
of the Background graphics which exist within the Same byte as object 
graphics will .be lost). The color generators are treated in the Sane 
manner @s above. This gives the effect of the Mobile object “breaking 
holes" in the background as it moves through a pattern. See figure 3 
for an illustration of this mode. 

The Jimitation of only being able to Gisplay two colors within the 
Same Jine of a pattern position force the above compromises when 
combining object and background generators. Which method should be 
used in a given situation will depend on the @raphics and color of 
both the background and the object. Experimentation will be necessary 
to determine which method produces the least Gisruption of the 
Background graphics. 


Another option gives the programmer control over the choice of colorod 
for any color generator bytes which have had their colori changed to 
the object's color. 


If bit 1 of register B is 0, then the colorO of the above-mentioned 
color bytes will not be changed. . 


If bit 1 of register B is 1, then the colorOd will be changed to 
transparent (thereby causing the backdrop color to be Gisplayed as the 
colord). 


Figures 4 and S illustrate these last two modes of operation 
tTespectively. 


The new pattern and color generators are moved to the object's 
generator tables as follows: 


Each Mobile-Object will have table space assigned to it (within 
the VRAM pattern and color generator tables) for 18 pattern and 
color generators. These tables are divided into an upper and a 
lower half. When a Mobile-Object is displayed, the “active" 
generators (i.e. those currently being used to display the object) 
will reside in either the upper or lower half of its generator 
tables. The half which is not in use is indicated by bit 7 of 
FRAME in that object's status area. This bit will be 0 when the 
lower half is not in use and 1 when the upper half is not in use. 
PUT_MOBILE moves the new generators to the half of the table not 
in use and also complements bit 7 of FRAME. This procedure 
enables the new generators to be moved to VRAM Without disturbing 
the current display. If this were not done, it would be possible 
for one TV field to display partially updated generators and 
thereby ezuse the object to flicker. 


Once the new set of pattern and color generators are moved to the VRAM 
pattern and color tables, PUT_MOBILE éisplays the Mobile-Object by 
writing the names of these new generators to the pattern name table in 
order to 6isplay the object at the called for location. In addition 


— 
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the pattern names which are Overwritten in the process of Sisplaying 
the Mobile-Object are Saved, and then restored to the meme table, i¢ 
necessary, when the object moves. 


NOTE: 
Due to an error near the beginning of the PUT_MOBILE routine, the 
beginning part of. PUT_MOEBILE will have to be included as part of the 
Cartridge progran. Instead of calling PUT_OBJECT for mobile objects, 
it will Be necessary to call the version of PUT_MOBILE which will 
reside in cartridge ROM. This has the following two side effects: 

1. Mobile-Objects Bay not be components of a Complex object. 

2. The defered write condition will not be recognized by 
PUT_MOBILE. 


The following is the section of PUT_MOBILE which must be incorporated 
as part of the cartridge Program: 


WORK_BUFFER EQU 8006H 
FLAGS EQU 3 
FRM EQU 4 
YDISP EQU ) ‘ 
IDISP EOQU i 
YP_BK EQu 16 
IP_EK EQU 17 
PX_TO_PTRN_POS EQU 07E8H 
CET_BKGRND EQU 0898H 
PM2 EQU OAEOH 
PUT_MOBILE LD IY, {WORK_BUFFER) ; IY := ‘WORK_BUFFER 
if in GRAPHICS MODE 1 
RES 7,B 
if in GRAPHICS MODE I! 
SET 7,B 


LD CIY+¢FLAGS),B 
PUSH HL 
LD H,CIX49) 
LD L, (1X42) 
LD A,CHLI 
LD CIY¢FRMI,A 
XOR 80H 
LD {HL},A 
INC HL 

: ‘ LD £, CHL) 

: LD A,E 

AND 7 
NEG 
ADD A,8 
LD CIY+XDISPJ,A 
INC HL 
LD D,CHLI 
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CALL PX_TO_PTRN_POS 
LD CIY+¢XP_BKI,E 
. INC HL 
LD E, CHL) 
LD A.E 
AND 7 
LD CIY¢YDISPI,A 
INC HL 
LD D,{KLI 
CALL PX_TO_PTRN_POS 
LD CIY¢YP_BKJ,E 
LD HL,{WORK_BUFFER) 
LD DE, YP_BK+i 
ADD HL,DE 
LD D,CIY¢YP_BK) 
LD E, LIY¢XP_BK) 
LD BC,303H 
PUSH IX 
CALL GET_BKCRND : 
POP 1X 
JP PM2 : 


The calling sequence for Mobile-Objects is: 


LD IX,HIGH_LEVEL_DEFINITION 

LD HL,CGRAPHICS 

LD £,MODE +; See above discussion for 
+ parameter passed in reg B 

CALL PUT_MOEILE 


An additional patch is needed when Operating in GRAPHICS MODE 1. In 
this case the last instruction in the above code (JP PM2) ig replaced 
with the following eode: 


PUSH 12 i Save another copy of object pointer 
CALL PM2 + Call rest of OS PUT_MOBILE routine 
POP 1X + Restore object pointer 
LD IY,3 i; Set up for 3 item VRAM write 
LD A, CIX+é3 > Cet FIRST_CEN_NAME 
LD B,A > And save another copy 
AND A,? + Evaluate MOD 8 
CP 7 > If NE 7 then 
JR NZ,THREE_GEN ; 3 generators to move 
LD Iy,4 > Else, move 4 generators 1 
THREE_CEN LD A,B s A :# FIRST_CEN_NAME 
SRL A + Divide by 8 
SRL A 3 to get index into 
SRL A ; color table 
LD E,A > DE gets pointer to ebject's 
LD D,0 ; eolor gens in VRAM 


LD KL,W_BUF+¢88H ; Point to 4th gen 
PUSH HL +; Save pointer 
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LD A,CHLI 
1D 8,3 s Copy this generator 3 times 
COPY3 TNC HL : 
- ED CHLI,A 
DINZ COPY3 
POP HL + Get back pointer 
LD A,4 ; Code for color table 
CALL PUT_VRAM ' 
RET 


W_BUF is the address of the work area for OS routines (i.e. the 
address stored at WORK_BUFFER, 8006H, in cartridge ROM). 


NOTE: In applications where the background color (eolor0d) of the 
patterns over which the mobile object is to move and the color of the 
mobile object itself does not change, the above patch will not be 
needed. Instead it is sufficient to initialize the color generators 
for the mobile object to the desired colori/eolor0 combination. 


7.3 PUT_SPRITE : 
This routine handles the display of all sprite objects; sise0, sisei, 
magnified and unmagnified. 


The routine uses SPRITE_INDEX in the object's high level definition to 
Getermine which of the 32 sprites to use to implement the object. 
Positional information from X and Y_LOCATION in the object's STATUS 
area is used to update the wertical and horisontal position entries in 
the sprite attribute table in VRAM. The routine facilitates Sprite 
objects bleeding off to the Jeft as well as completely off the screen 
by making use of the early clock Bit. 


Frame information for Sprite objects comes from the FRAME_TAELE in the 
ebject's CRAPHICS data area. Each frame is specified by a COLOR and ea 
SHAPE Byte. The SHAPE byte is added to the object's FIRST_CEN_NAME 
(the second entry in the object's CRAPHICS data area) and this sum is 
then moved to the name entry position in the sprite attribute table. 
Bit 7? of the COLOR byte is modified to reflect the required state of 
the early clock bit and then moved to color entry in the sprite 
attribute table. 


7.6 PUT_COMPLEEX 


A Complex object is a collection of “component” objects. Each frame 
of a Complex object specifies the positional relationship and frame to 
be csed for each of the component ebjects. The positional 


relationship fer all the component objects is defined in an offset 
list and the franze for each component is defined in a frame list. 

There is one offset list and one frase list for each frame of the 

Compler object. 
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PUT_COMPLEX takes the following steps to display Complex objects: 


dc 


Using the FRAME_LIST for the particular frame of the Complex 
object to be displayed, the frame of each of the Conponent 
ebjects is updated. 


X and Y_LOCATION for exch of the component objects is formed 
by adding the X and Y offsets for each component, a8 specified 
in the OFFSET_LIST, to the X and Y_LOCATIONS from the Comples 
object's STATUS area. Note: the offsets are 8 bit unsigned 
numbers, so the location of the component objects will always 
be to the right and/or Below the coordinate position indicated 
by © and Y_LOCATION in the Complex object's STATUS area. 


Each of the component objects is displayed by calling 
PUT_OBJECT for esch of the component objects. 
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8.0 DATA STRUCTURE SUMMARY FOR SEMI_MOBILE OBJECTS 
wee ROM DATA AREAS tee 


Migh Jewel éefinition for a Sewi-Mobile object; the address of the high 
level Gefinition (SMO) is passed to the Qrephics rovtines when called 
on to process the object: 
BHO DEFW GRAPHICS pointer to graphic data for object 
DEFW STATUS spointer to status area 
DIFW OLD_SCREEN j;pointer to save area for OLD_SCREEN 


Craphics for semi_mobile objects are defined as follows: 


GRAPHICS DEFSB OBJ_TYPE sLSN = 0, MSN used only in Graphics Mode J1 
iMSN bits 5,6,7 indicate which thirds ef 
Generator tables to move generators to 
iif bit 7 then move gens to upper third 
s3¢ oo 6 e e s e pidédle td] 
.* « 5 a a a * lower oo 
chit @ indicates how many color generator 
ibytes per pattern generator to expect, if 
bit 4 = 0 then & bytes/gen else 1 byte/gen 

DEFE FIRST_CEN_NAME ; index into VRAM tables where object's 
igenerators are located 


DEFB NUMCEN smumber of ROMed generators for object 
DIFw CENERATORS ;pointer to first of ROMed patterns 
DEFW FRAME_0 spointer to first frame data 

DIrw FRAKME_1 spointer to second frame 

DEIFW FRAME_s sPoiater to Nth frape 


The data for each frame is organized as follows: 


FRAME_o DEFe I_EITINT sJ_LEXTENT and Y_EXTENT are the width and 
DEFEB Y_EXTENT cheight of the frame in pattern plane positions 
DIFB NAME_6 sNAME_@ threugh KAME_a are the names of the 
DEFB NAME_1 ipatterns used for this frame. There aust 
Fs ; cezactiy Z_EXTENT * Y_EIXTENT names ané they 
DEFE NAME_n iBust be arranged in a ROW major array, as 


cthey are te be displayed on the screen (i.e. 
ithe pattern representing NAME_O will appear 
cat the upper-left corner of the frame, NAME_n 
swill appear at the lower-right corner). 


The pattern generatere are stored as follows: 


GENERATORS DEFB bb bb, bb, bb, bb, bb, bb,b ;where bb = binary graphic data 
DEFE bb,bb,. bb, bb, bb, bb, bb, Bb ; 


DIFs bb. bb bb, bb, bb, bb, bb, bb 
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Each group of 8 bytes Corresponds to one generator. These Generators are 

all poved te VRAM by ACTIVATE. The first Generator will be located at FIRST_ 
CEN_NAME (in Craphiecs Mode II, the MSN of OBJ_TYPE indicates which thirds of 
the generator tables will be initialised). 


There are three possible formats for color Generators. The first two are 
used in Craphics Mode-II, the third in Graphics Mode I: 


GRAPHICS MODE 11: 


1. If bit @ of OBU_LTYPE is @, then there must be 8 color generator bytes 
per pattern generator. The MSK ef each byte specifies coleri for the corresponding 
pattern generator byte. The LSN Specifies color0. (Ci.e. if the first color 
generator looks like: DEFE 1F,1F,1F,1F,39,39,39,39 , then the first 4 lines of 
the corresponding generator will have a colerisBLACK and colorOsWHITE and the 
Tast @ lines will have colorieLIGHT CREEN ané colorQeLIGHT RED.) 


DEFB ee,ce,ec,cc,cc,ec,cc,ecc ;Color generator for ist pattern 
DEFB ec,ce¢,c¢c,¢e,¢¢e,ec,ec,ec ; ® * “  @nd . 
DEIFEB €c,ec,ec,¢¢,¢e,e¢c,ec,ec ; * ad “Jast * 


2. %QIf bit 4 of OBJ_TYPE is 1, then only one color generator byte per 
pattern generator will be expected. This byte will be duplicated 8 times by 
the ACTIVATE routine when Boving the generators to VRAM. Each byte has the 
Sime format as above. There must be ene byte per pattern generator. 


DEFB ec iColor generator for ist pattern 
DIFEB ec : ™ : - ©  3né = 
DIFB ec 7 = “ * JIast = 


CRAPHICS MODE I: 

3. In Graphics Mode 1 the pattern Generator table can be thought of as 
Givided up into 32 groups of 8 generators. Each group of pattern generators 
Share the ssee color generator byte. Therefore, there must be one color 


generator byte for each group which contains pattern generators for the 
object. 


ee2 RAM DATA AREAS tn8 
The status area for semi_mobile objects is as follows: 


STATUS . DEFS i iFrame number to be displayed 


DEFS 2 tX_LOCATION, low byte first 
DEFS 2 sY_LOCATION, low byte first 


iJ and Y_LOCATION used by game program to 
sposition ebject on screen and are 16 bit 
sSigned aumbers 

DEFS i iNEXT_CEN, index to area for adding new 
sGeneraters 
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Old_screen Gata has the following structure (if OLD_SCREEN ( 7000H, then 
it is in WRAM, else it is in CRAM): : 


OLD_SCREEN DEFS 


DIFS- 


DIFS 
DEFS 
DIFs 


i 


= we 


i3_PAT_POS, column in which the SBpper Jeft cerner 
Of saved screen lies. This byte initialised to 
i80H by ACTIVATE to indicate no Gate Saved yet. 
iY_PAT_POS, row in which upper left corner of 
iBaves screen lies. 

sZ_EXTENT ef saved screen 

sY_LEXTENT of saved screen 

Where m= the largest screen that will need to 
ibe seved (i.e. the Targest value of ZY_EXTENT * 
iV_EITENT for any of the frames of this object). 
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9.0 DATA STRUCTURE SUMMARY FOR MOBILE OBJECTS 


#t® ROM DATA AREAS ene 


High level éefindtion for Mobile ebjects; the address ef this data block 
(MOB) is passed to the various gtaphics routines when precessing the object: 


MOB DEFW GRAPHICS spointer to graphic data for object 

DEFW STATUS spointer to status area 

DIFW OLD_SCREEN ;pointer to save area for OLD_SCREEN 

DEFE FIRST_GEN_NAME ;inder inte VRAM tables where ebject's 
"active" generators are located, i.e. 
sthose being used to Gisplay the object 
iSpace for 18 generators most be reserved 
ifor each Mobile object 


Craphics for a mobile object are Cefined as follows: 


GRAPHICS DEFB OBJ_TYPE ;LEN » 3 
DEFE NUMCEN imumber of ROMed generators for object 
DIFW NEW_GEN spointer to space for creation ef new 


sgenerators 7 
DIFW CENERATORS j;pointer to first ef ROMed patterns 


DEFW FRAME_0© spointer to first frame data 
DIFW FRAME_1 ipointer to second frame 
DIFW FRAME_n ipointer to Nth frane 


The data for each frame is Organized as follows: 


FRAMI_a BEFE WAME_&, MAME_B.NAME_C,NAME_D, COLOR 
swhere the pattern 
for NAME_A will appear in the upper left 
icorner, NAME_B in the lower left, NAME_C 
sin the upper right and NAME_D in the lower 
sright. The MSN of COLOR specifies the 
itolor for the frame (e.g. if MSNe? then 
oifrawe will be CYAN) the LSN must « 0. 


The pattern generators are stored as follows: 


GENIRATORS DEFB bb.bb, bb, bb, bb,bb, BE, Bb swhere bb se Binary graphic data 
DEFB bb, bb, bb, bb, bb, Bb, bb, bb 


" DIFB bb, bb, bb, bb, BS, Bb. BD BD 

Each group of 8 bytes Corresponds to one generator. Each generator is 
referesced by its position in the the table. The value of the first generator's 
name is 6, the value of the second generator's name is 1 etc. New generators 
Created at game-en tine and stored at (NEW CEN) continue in the numbering 
Sequence. (i.e. if there are 8 generators in ROM, numbers 0-7, then generator 
neoeber 8 reffers to the first generator in a table starting at (NEW_CEN), ete.) 
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@en RAM DATA AREAS #28 
The structure for a mobile ebject's status is as follows: 


STATUS DEFS 1 ithe lewer 7 bits specify the frame to be 
sGisplayed, bit 7 indicates whieh VRAM table 
;area is in use and must not be altered when 
: sehanging the frame number 

DEFS 2 sX_LOCATION., low byte first 

DIFs 2 sY_LOCATION, low byte first 
iZ and Y_LOCATION used by gawe progree to 
seOsition object on screen and are 16 bit 
:Signed numbers 

DIFS 2 sNEW_CEN, points to area for adéing new 
sGenerators 


Old_screen data has the following strocture (if OLD_SCREEN ¢( 7000H, then 
it is in VRAM, else it is in CRAM): 


OLD_SCREEN DEFS i sZ_PAT_POS, eolumn in which the upper left 
scorner of saved screen lies. This byte 
vis initialised to 80H by ACTIVATE to indicate 
sthat there is no data saved get. 


DIFS 1 sY_PAT_POS, row in which upper left corner of 
ssaved screen lies. 
DIFSs 9 iNine Background names, arranged in ROW wajor 


;order. 
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10.0 DATA STRUCTURE SUMMARY FOR SPRITE OBJECTS 
wae BOM DATA AREAS ene 


High level definition for Sprite objects; the address of this data block 
(SP_OBJ) is passed to the various graphics routines when processing the ebject: 


SP_OBJ DEFW GRAPHICS ‘ spointer to graphic data for object 
DEFW STATUS spointer to status area 
DIFB SPRITE_INDEYX iSprite number for this object (€-31) 


Craphics for a sprite object are defined as follows: 


CRAPHICS DEFBs OBU_TYPE iOBJ_TYPE «= 3 
; DEFE FIRST_GEN_NAME ;mame of first sprite generator 
DIFW CENERATORS spointer to ROMed generators 
DEFB NUMCEN smumber of ROMed generators for object 
DIrw FRAKE_TABLE spointer to table of frame data 


The data for each frame is organised as follows: 


FRAME_TABLE DEFE COLOR isprite's color for this frame 
DEFB SHAPE offset from FIRST_CEN_NAME (generators 
sto be used for this frame) 
DEFB COLOR iSecond frame ecoler 
DIFB SKAPE sSecond frame generator 
DIFE COLOR sJast frame eelor 
DEFB SHAPE ilast frame generator 


The pattern generators are stored as follows: 


CENERATORS DEFB bb, bb, bb, bb, bb, Bb, Bb, bb ;where bb = binary graphic data 
DEFB bb, bb,bb, bb, bb, bb, bb, bb 


DIFs Bb.ob bb, bb, bb, bb, Bb, bb 
#28 RAM DATA AREAS 2a28 


The strocture for a mobile object's status is as follows: 


STATUS DEFS i iFrame number to be displayed 
. DEFS 2 sX_LOCATION, low byte first 
DEFS 2 sY_LOCATION, low byte first 


sX and Y_LOCATION used by game program to 
ipesition ebject on screen and are 16 bit 
7signeéd sunmbers 

DEFS i sNEXT_CEN, index of free space in 
sGenerator table 
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11.06 DATA STRUCTURE SUMMARY FOR COMPLEX OBJECTS 
eek ROM DATA AREAS e228 


High level éefinition fer Complez ebjects; the address of this data block 
(COM_OB) is passed to the warious Graphics routines when Processing the object: 


Com_oE DEFW = GRAPHICS spointer to graphic data for object 
DEFW STATUS spointer to status area 
DIFw OB JECT_1 spointer to component object 1 
DEFW OBJECT_2 ; * " . 2 
DIFW OBJECT n ; * * = n 


Craphics for a Complex object are Gefined as follows: 


CRAPHICS DEFE OBU_TYPE «MSN of OBULTYPE = number of component 
H objects (must equal number 
H ef high level object addr) 
iLSN of OBU_LTYPE = 4 
DIFW FRAME_LIST_6 ipointer to frame list for first frame 
DEFW OFFSET_LIST_O ipointer to list of offsets for first 
frame 


DErw FRAME_LIST_n spointer to frame list for Jast frame 
DEFW OFFSET_LIST_n spointer to list of offsets fer last 
frame 


Each frame ef a complex ebject is defined by a Jist of frame nusbers and another 
list of offsets. Each entry in the FRAME_LIST specifies the frame to be displayed 
fer one of the component objects. The first entry specifies the frame number for 
the first component object, the second entry specifies the frame number for the 
second, ete. 


FRAME_LIST_a BEFE £1 iframe number for first component 
DEFB {2 iframe number for second component 


DIFS fn iframe mumber for last component 
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The OFFSET_LIST specifies the location of each of the component ebjsects with 
respect to the X and Y_LOCATION given in the Complezr object's STATUS area as 


follows: : 


OFFSET_LIST_n DEFB 


ebject 
DEFEB 
object 
DEFB 
DEFB 
DIFE 
DEFEB 


wee BAM DATA AREA a8 


Status area for a Complex object: 


STATUS DEFS 
DEFS 
DIFSs 


Idisp 
Ydisp 


Idisp 
Yéisp 


Idisp 
Ydisp 


i 
2 
2 


iXéisp = amount first component Gisplaced 
shorizontally from X_LOCATION of compler 


iYdisp © amount first component displaced 
ivertically from Y_LOCATION of complex 


isame for second component 


iSawe for last component 


iFrame number to be displayed 


:X_LOCATION eof ebject 
sY_LOCATION of object 


COLECOVISION 
GRAPHICS USERS' MANUAL page 44 


Figure 1 


This figure illustrates the Telationship between the Meta-Plane and 
the Pattern Plane. Y_LOCATION and YLLOCATION are sixteen bit signed 
warisbles which determin the location of an ebject's upper-left 
corner. These variables are part of each object's STATUS area ia CPU 


RAM. 


Ee fe ey 
— 


l Lipps fe i 

pt are 
Med Te Tit a 1 | ft a ee 
OG eRoSopeeeeeeeeceesenrcebeeiaseeeeees 
| BER a eee ‘. 

4] SERRE RMSE RA EEE ae ERS DRAE EE 
Pt ESE Re See E eee eee 

Zs ERERRERE Rae SESERS eRe 


SSURRE PRA Dee ARR l 
= 
SRECE DERE RAM SRE 


sssiecesecs orton: OUSREE5 5000500 Reese ro 


SaeMEe b TRSRER HASSAN Lil 
SRESEP GREE BRS Eee eee ee ee ee 
Sun canssnne GuPSGGESEN' SEESETESSEETETSSSTTSEETETEEEEETEEE 
CECE A HY yee re 


= EEE EEE EEE 
ot 

ee ge SERERE SRR Eee ee pt 

SS S00 Sh RESO Cee Ke Eke SSERER SRE cam. 

py tf aan HH om: 

t | eee BEERS ERASE COREE REAR ERE 
Sis peensssusaseennsSessecesrsseeeereeseeseresssessrsse== 
ERee ee ae oa 
pies tO eee ree Ze 
See aR ee 

vas 


sun Be RAAESE CoEE ESSE SES oUSEEEEEEEssEeeeseerseesees feaaess 

Soganessard afassnsontannosestestas santansstesezts eomeaes 

Ger eteets ocestesttstases foasestocsitteccsatcees aemae 
eufcesestas estastsizestostestosses tevesams 
| SERRE SRRSSSEeeeEeeeee Fineness 

ce Sussdestectostandastcstestes fossenee feetoass 

Seeassedred afaetonesestestestestostontentastontar feczems 

; Stree SESTSSSEEEEEEESEEEE 

Lt i | SREPASR RRA 

H H+] He 

BSH Sryrestee Sresteresnerfire 

CH SEEEEELESEEEEE 

sifie Seeiiseeereeitaeer 


| i ae 
achenavay 


page 45 
MOBILE uses 
A paramenter passed 


UT 


B, selects which ef the four methods will be 


Tepresents the colorO ef the background 
represents the colori of the background 
represents the celer ef the Mebile ebject 


represents the backdrop color 
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22s CONTENTS eee 


BUMMARY OF FEATURES 


GENERAL DESCRIPTION 

Song data areas, SxDATA: RAM Map mode of sound chip operation 
Note list storage and note headers 

LST_OF_SND_ADDRS and PTR_TO_LST_OF_SND_ADDRS 
Hietarchy of song data areas: truncation, priority, overwriting 
The four basic routines, briefly 


NOTES : 
Terminology 

Frequency sweeps and note duration 
Attenuation sweeps 

Rests 

Type 0: fized frequency, fized attenuation 
Type 1: swept frequency, fixed attenuation 
Type 2: fixed frequency, swept attenuation 
Type 3: swept frequency, swept attenuation 
Noise notes: special case Type 2 notes 


OPERATING SYSTEM ROUTINES 
INIT_SOUND 
ALL_OFF 

JUKE_BOX 
SND_MANAGER 
PLAY_SONGS 
FREQ_SWEEP 
ATN_SWEEP 
PROCESS_DATA_AREA 
LOAD_NEXT_NOTE 
UTILITIES 


SPECIAL SOUND EFFECTS 

Sound effects as notes within a song ("note effects") 
A sound effect as a single sound 

Pseudo code listing of main routines 


SxDATA 
Note Header 


" LST_OF_SND_ADDRS 


Rests and Type 0: fized frequency, fixed attenuation 
Type 1: swept frequency, fixed attenuation 

Type 2: fixed frequency, swept attenuation 

Type 3: swept frequency, swept attenuation 

Noise notes: special case Type 2 notes 

Dedicated cartridge RAM locations 
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The Colecovision Operating system includes routines which allow the cartridge 
Programmer to store "songs" and simple sound effects in tabular form in 

cartridge ROM, and play them on request Guring the game. More complex, special 
Sound effects can also be created and played within the same data structure and 
Procedural format. This Sound Users' Manual Gescribes the data structures 
expected by and the use of the operating system sound routines. 


SUMMARY OF FEATURES 


® six song note types: combinations of fixed or variable frequency and 
attenuation, “noise” (percussion) notes, and rests 


* hierarchical structure of local data areas assigned to each sound channel, 
which allows the temporary "overwriting" of lower priority songs (i.e., lower 
Priority songs are not truncated by higher priority songs or sound effects that 
use the same channel, but continue unheard until the higher priority songs 
finish) 


® the ability to easily include a special sound effect (say, a cymbal crash) 
as part of a song composed Primarily of musical tones 


& both songs and special, independent sound effects (e.g., an explosion sound) 
can utilize the same data structures and output procedures 


& sweep routines, which automatically create frequency or attenuation sweeps, 
Simplify note data storage and can be used by specia! sound effects 


® song end codes allow songs to be played once, or automatically restarted 
upon completion (repeat forever) 
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GENERAL DESCRIPTION 
® Song data areas, SxDATA: RAM map mode of sound chip operation 


The Colecovision operating system provides sound routines which output 
frequency, attenuation, and control data to the T! 74489 sound chip. Data to 

be sent to a particular sound generator channel is expected to be stored within 

a ten byte block of CPU RAM called’a “song data area". A song data area, then, 
contains a RAM record of the current values “playing" on a sound channel. 


Each song data area can also contain timing and descriptive information which 
allows for simple generation of musical notes. A "song" can be created by 
storing in CART ROM a list of note parameters which specify note duration, 
frequency, and attenuation. When a song is started, O/S routines are provided 
to load the data describing the first note of the song into a song data area. 
Each song data area is then processed at regular intervals by routines which 
modify and output the area's data to the sound chip. When a note is completed, 
the next note in the song is automatically loaded and the process continues. 


O/S routines also exist which facilitate the creation of “special effects": 
sound routines written by the cartridge programmer which algorithmically 
generate data to be sent to the sound chip (as opposed to the table look-up, 
song approach). 


RAM space for at least four song data areas must be reserved by the cartridge 
Programmer: one each to describe the current status of the four sound chip 
channels. More than four song data areas will be Tequired if the ability to 
"overwrite" lower priority songs is desired, and some songs may share the same 
data area (see the following discussion, “Hierarchy of song data areas: 

priority, truncation, overwriting"). The first byte in each song data area, 
byte 0 (its offset from the beginning of the data block = 0), contains the 
channel number upon which the song is to be played (0: noise generator, 1 to 3: 
tone generator) and the song's identification number (SONGNO: 1 to 61). A song 
data area is referred to throughout the rest of this manual as "SxDATA", where 
x = the song's SONGNO. For a detailed Sescription of each byte in a song data 
area, see the following discussion, "NOTES", and refer to Figure 1. 


® Note list storage and note headers 


A note list is a sequential! list of frequency and timer data stored in 

cartridge ROM that, when processed and output to the sound chip, create the 
notes that comprise a song. Each block of 1 to 8 bytes of data that describes 
a note in the list must begin with a one byte header which contains information 
(bit flags or values) that indicate (see Figure 2): 


1) The number of the channel upon which to play the note 
2) The note type (one of 4 combinations of fixed or swept 
frequency and attenuation, plus a rest). 


The single byte header can also be used as an end-of-song marker, a repeat-song 
indicator, or an indicator that a "note" is to be determined algorithmically by 

&@ Special sound effect routine (the starting address of which immediately 
follows). 


A 16 bit pointer to the location of the header of the next note to be played 
(NEXT_NOTE_PTR) is maintained by the O/S routine SND_MANAGER in each song's 
Gata area (SzDATA, offsets 1 and 2). 
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* LST_OF_SND_ADDRS and PTR_TO_LST_OF_SND_ADDRS 


The O/S routines expect the ten byte long song data areas to be stored 

contiguously in CPU RAM, starting with the data area used by song number one. 

The beginning addresses of each of these data areas, as wel] as the addresses 

of the headers ot the first note in each song, are stored in a ROM table calles 
LST_OF_SND_ADDRS (see Figure 3): The cartridge programmer may place this table 
wherever desired in ROM. The O/5 routines know its starting address through a 
Gedicated CPU RAM location, PTR_TO_LST_OF_SND_ADDRS, which must be loaded with 
the 16 bit address of the table by the cartridge program before calling any O/S 
routines which use it (see description of INIT_SOUND). 


® Hierarchy of song data areas: truncation, priority, overwriting 


The routine that does the processing of the note data stored in the song data 
areas, SND_MANAGER, and the routine that “outputs the modified data to the sound 
chip, PLAY _SONCS, are designed to be called by the cartridge program every : 
Video Display Processor (VDP) interrupt (every 16.7 ms). Starting with the 

Gata area for song number one, SND_MANAGER processes the appropriate timer and 
Sweep counters and modifies the frequency and attenuation data accordingly. If 
the data area is assigned to a Special effect, SND_MANAGER calls that effect. 
When a note is finished, SND_MANAGER, using the data area's next note pointer, 
moves data for the next note of the song into the area. ia 
After the operations upon a data area have been performed, the sound chip 
channel number (CH) stored in byte 0 of that data area is consulted and the 
appropriate “channel data area pointer" (PTR_TO_S_ON_x) is set to point to the 
beginning of the data area just Processed (four of these pointers exist at 
Sedicated 16 bit locations in CPU RAM, one for each of the sound generator 
channels). The following data areas are then processed in the same fashion, in 
order of occurence, until the end of data area code, 00, is reached. If a data 
area is inactive, i.e., if the song(s) that use it aren't playing at the 

moment, SND_MANAGER simply passes it over, Going no processing or channel! data 
area pointer modification. 


PLAY_SONCS, usually called immediately prior to SND_MANAGER, outputs data to 
the sound chip from the four song data areas pointed to by the channe! data 
area pointers. Thus, a channel output Priority is established on the basis of 
ordinal position within the data area block: the last data area processed that 
uses a given channel is the one that will be played on that channel. E.g¢., 


order of data area 
within data block 


containing all songs that use this data area: 
song data areas SONGNO/CH# song is to be played on 
ist i/CHéx (remember: although other songs may use 


this data area also , song 1 MUST use it) 


Sth 6/CHA2 
. 6th 3/CH82 


7th : 11/CH&2 


i0th 2/CHE3; 4/CHE3; 7/CHE3 
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First, consider channel 2. Let's Say that the only songs which use channel 2 
are assigned three contiguous song data areas, Sth through 7th (grouping songs 
which use the same channel! isn't necessary as far as the code is concerned, but 
it makes it simpler to think about). SND_MANAGER, as it makes its way through 
the song data areas in order, will Process the Sth data area (which “belongs” 

to song 6) and set PTR_TO_S_ON_2 to the address of byte 0 in the Sth data area. 
Then, the é6th area will be processed, resulting in resetting PTR_TO_S_ON_2 to 
the 6th data area (song number 3). ’ Likewise, the 7th data area will be 
Processed, finally leaving PTR_TO_S_ON_2 pointing to the 7th data area (gong 
number 11). The next time PLAY_SONCS is called, it will send to sound chip 
channel 2 frequency and attenuation data in the data area pointed to by 
PTR_TO_S_ON_2, namely, the data for song number 11. 


Note that although only song 11 will be heard on channel 2 this pass through 
PLAY_SONCS, the timers and data for songs 6 and 3 were nonetheless modified, 
Tegardless of the existence of the higher priority song 11. That is, all songs 
“keep going", whether or not their data wil] be output during PLAY_SONCS. 
Songs 6 and 3 are said to have been “overwritten” by song 11. Should song 11 - 
become inactive (end) before song 6 and/or song 3, then the highest priority of 
the remaining active songs (i.e., the last data area within the block of data 
areas to use a given channel) will be heard. 

Thus, assigning several data areas to songs which use the same channel! allows 
the creation of "background" songs which can be momentarily interrupted 
(overwritten) by a higher priority song or sound effect (e.g., an explosion, or 
a bonus song) and continue on after the overwriting song is over. 


Now examine the 10th song data area. Again, let's say that the only songs that 
use channel 3 are shown here and that they all share the 10th data area. In 
this case, the programmer may have arranged things such that songs 2, 4, and 7 
are never active simultaneously: i.e., there was no reason to assign three 
different data areas for songs which never overlap. If, however, this is not 
the case and, say, song 4 may be started before song 7 is finished, the 0O/S 
routines would stop song 7 in favor of song 4. That is, for songs that share 
the same data area, the most recent song started is the song heard, and 
interrupted songs do not continue: i.e., songs sharing the same data area 
truncate each other. In many cases this may be both acceptable and desirable, 
as it saves RAM space. 


NOTE: The preceeding description states that a channel data area pointer is 
upcated every time SND_MANAGER processes a song data area: this is actually not 
the case. To save processing time, a routine which updates all the pointers is 
called only when, after loading the next note in a song, SND_MANAGER detects 
that the data area's CH@ or SONCNO has changed. This happens whenever the nert 
note: 1) uses a different channel (see "Noise notes: special case Type 2 

notes), 2) is a special effect note, or 3) is an end-of-song indicator. It is 

only necessary to update the channel data area pointers in these cases, and 

when a new song is started (in JUKE_BOX). See "Pseudo code versions of main 
routines". 


* The four basic routines, briefly 
The following four O/S routines are the only ones that need be called to create 


songs which use the six standard note types (more complete descriptions of each 
routine can be found in the “OPERATING SYSTEM ROUTINES" section): 
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INIT_SOUND: This routine should be called immediately after power on, before 
any sound processing can occur. It turns off the sound generators, initializes 
the CART RAM locations to be used as song data areas, sets up the four channel 
Gata area pointers, and initializes PTR_TO_LST_OF_SND_ADDRS. 


INPUT: n 

TYPE: 8 bit constant 

PASSED: inB. ‘ 

DESCRIPTION: number of song data areas used by the game 


INPUT: LST_OF_SND_ADDRS 

a YPE: 16 bit address 

PASSED: in HL 

DESCRIPTION: LST_OF_SND_ADDRS is the base address of a list of the starting 
addresses of each song's data area and note list. 


OUTPUT: 1) turns off all sound generators - 
2) initializes PTR_TO_LST_OF_SND_ADDRS 
3) writes the inactive code (OFFH) to byte 0 of the n song data areas ~ 
4 stores 00 at end of song data areas 
S) sets the 4 channel song pointers to a dummy inactive area 
6) sets SAVE_CTRL to OFFH (see “Noise notes" discussion) 


‘JUKE_BOX: JUKE_BOX is called to start a song. Using a song number passed in B, 
JUKE_BOX loads the data for the Song's first note into the appropriate song 

Gata area, thereby truncating whatever song had been “playing" in that data 

area. (The address of the appropriate area is found by using the song number 

as an index into the LST_OF_SND_ADDRS table). It also formats the data area's 
header and sets up the next note pointer. If the song is a special sound 

effect, its next note pointer is set to the address of the special effect 

routine. The next time PLAY_SONCS is called, that song's first note will be 
played. 


If JUKE_BOX is called with a song number of a song already in Progress, it 
returns immediately (i.e., tt doesn't restart the song). 


INPUT: song number to be started 
TYPE: & bit constant, 1 to 61 
PASSED: in B 


CALLS: PT_IX_TO_SxzDATA, LOAD_NEXT_NOTE_PTR, UP_CH_DATA_PTRS 


OUTPUT: 1) moves the song's first note data to the appropriate song data grea 

1) formats byte 0 header of the song's data area : 

2) points next note pointer in data area (bytes 1&2) to address of 

first note in song, or address of Special sound effect routine 

SND_MANAGER: SND_MANAGER should be called every VDP interrupt (every 16.7 ms). 
For each data area, SND_MANAGER processes the appropriate timer and sweep 
counters and modifies the frequency and attenuation data accordingly. If the 
data area is assigned to a Special effect, SND_MANACER ealls that effect. 
When a note is finished, SND_MANACER, using the data area's next note pointer, 
moves data for the next note of the song into the area. If SND_MANACER reads a 
header byte (in CART ROM) that has bits 364 set, indicating repeat song, it 
will start the song again by reloading the first note in the song. 


After the operations upon a data area have been performed, if necessary, the 
channel data area pointers (PTR_TO_S_ON_x) are updated. The following data 
areas are processed in the same fashion, in order of occurence, until the end 
of Gata area code, 00, is reached. 
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SND_MANAGER does not output the modified frequency and attenuation data. 
PLAY_SONGS is called just before SND_MANAGER to do this. 


Special codes in byte 0 of the song Gata area indicate: 


235: Gata area inactive, do no Processing 
62: & special effect is to be played; SND_MANACER ealls the effect routine 
0: end of song data areas (SND_MANAGER processes data areas until it sees 
@ in byte 0) 


NOTE: Song number 1 MUST use the first area in the block of song data areas. 


INPUT: none 


CALLS: PT_IX_TO_SxDATA, PROCESS_DATA_AREA 


OUTPUT: Calls routines which: . 

1) decrement song duration and sweep timers 

2) modify swept frequency and attenuation values 

3) call special effects routines where necessary 

@ update the channel data area pointers if necessary 

5S) restart the song if indicated . 
PLAY_SONCS: PLAY_SONGS takes the frequency and attenuation data pointed to by 
the four channel data area pointers (PTR_TO_S_ON_x#) and outputs it to the four 
sound chip generators. 


" INPUT: none 
CALLS: TONE_OUT, UPATNCTRL 


OUTPUT: 
1 


~ 


current freq and atn data is output to each tone generator, if 
song/effect on that channel is active; if song on that channel! is 
inactive, that generator is turned off 

2) noise generator is sent current atn data, and contro! data, if new 
3) modifies SAVE_CTRL if necessary , 


These four routines would normally be called as follows: 


power on inits done by 0/5 

cartridge program receives control: 

LD B, # of song data areas used in the game 

LD HL, address where LST_OF_SND_ADDRS is stored in ROM 
CALL INIT_SOUND to initialize song data areas 

whatever other power on inits you want to do 

start game: 


LD B, # of song you want to start 
CALL JUKE_BOX to set up for start of song 


VDP interrupt occurs: 

CALL PLAY_SONCS to output data 

CALL SND_MANACER to process song data 

whatever else you want to do Guring VDP interrupts 
RETN to game 
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NOTES 
® Terminology 


Each note in a song has an associated 10 bit frequency (except for noise notes) 
and 4 bit attenuation which is output to the sound chip every time PLAY_SONCS 
is called. The initial frequency and attenuation values (stored in 2 bytes) 

are part of a block of 4 to 8 bytes that Gescribe a single note within a song's 
ROM note list. The remaining bytes are used to indicate sound channel, note 
type, duration, and various timers and values associated with swept notes. 


The following are explanations of names and symbols used throughout this manual 
to refer to bytes, or segments of bytes, within both a note's ROM note list and 
a RAM song data area (see Figure 1): 

‘: ¢ ds a symbol used to graphically separate bits or nibbles within a byte 

Bx: means bit x of a byte, bit 7 being the most Significant bit 


byte x: refers to the offset of a byte within a data block, byte 0 being the 
first byte in the block 


MSN, LSN: MSN means the most significant nibble of a byte, LSN is the least 
significant nibble 


CH#: the sound channel upon which a note is to be played; 0 = noise generator, 
1 to 3 = the 3 tone generators 


SONGNO: the song number of the song playing in a song data area; 1 to 61; 
SONGNO 62 means a Special sound effect is using the data area 


NEXT_NOTE_PTR: 2 byte address of the ROM location of the data block for the 
next note to be played in a song 


FO - F9: the 10 bit frequency data to be sent to a sound chip tone generator; 
FO is the most significant bit; see data sheets, TI 76489 


ATN: 4 bit attenuation data to be sent to any of the four sound generators 


CTRL: 3 bit control data for sound chip noise genrator; FB NFO NF! (called 
SHIFT in this manual); see data sheets for details 


NLEN: 1 byte that directly or indirectly determines the duration of a note 


FPS: 4 bit frequency prescaler, used with NLEN to determine the length of a 
frequency sweep 


FPSV: 4 bit temporary storage location for FPS; this variable gets decremented 
every VDP interrupt, and is reloaded from FPS 


FSTEP: the size of a step in a frequency sweep, an 8 bit two's complement 
signed value that is added to the current 10 bit frequency at a rate determined 
by NLEN and FPS; 1 to 127, -1 to -128 


ALEN: 4 bit number of steps in an attenuation sweep 
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ASTEPS: ASTEPS is the Signed, @ bit size of a step in an attenuation Sweep; 
can take values 1 to 7, -1 to -B (MSB «= 1 means negative) 


APS: 4 bit attenuation Prescaler, used with ALEN to Getermine the length of a 
frequency sweep 


APSV: 4 bit temporary storage location for APS; this variable gets decremented 
every VDP interrupt, and is reloaded from APS 


® Frequency sweeps and note duration 


The time duration of a note = the number of passes by PLAY_SONGS through the 
note times 16.7ms (the VDP interrupt period). (note that the time the note is 
HEARD could be shorter: see “Attenuation sweeps" discussion) The number of 
PLAY_SONCS passes is always determined directly or indirectly by NLEN. NLEN, 
however, has two meanings, depending upon whether or not a note's frequency is 
Swept: 


Fized frequency notes - In this case, NLEN is decremented every VDP interrupt 
and therefore directly determines the length of a note: 


duration = NLEN ® 16.?ms 2 


NLEN should have values in the range 0 to 255 (0 =) 256), giving @ mazimun 
duration of ~ 4.25 seconds. 


Swept frequency notes - Here, the prescaler variable, FPSV, is decremented 
until sero before NLEN is decremented. Once FPSV goes to sero, it's reloaded 
from FPS; however, an initial value for FPSV, which enters into the calculation 
of the the length of the first step in the sweep, is stored in ROM along with 
the rest of the note's initial Gata, and it may be different from the reload 
value, FPS. Fora frequency swept note: 


note duration = C((NLEN -1) ® FPS) « initial FPSV) ® 16.7ms 


So, NLEN again determines note duration, but in an indirect fashion (in concert 
with FPS and the initial FPSV). 


In the case of a frequency swept note, NLEN can be thought of as one of four 
Parameters that describe the Sweep: 1) the starting frequency, 2) FSTEP, a 
Signed step size, i.e., a delta frequency that is periodically added to the 
current frequency, 3) the Prescaler value (FPS) which determines the length of 
time at any one frequency step, and 4) NLEN, the number of steps in the sweep. 


The duration of each step in the sweep is given by the following: 
Curation ist step «= initial FPSV ® 16.7ms 
duration all others =» FPS ® 16.7ms 


Frequency sweep parameter ranges: 
FSTEP - signed 8 bit two's complement number: 1 to 127, -1 to -128; an FSTEP of 
O tells FREQ_SWEEP that the note is not frequency swept, and the note's 


Guration is determined by Girectly decrementing NLEN (prescaler is disregarded) 


FPS - 4 bit frequency prescaler, used with NLEN to Getermine the length of a 
frequency sweep: 0 to 15 (0 =) 16) 
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FPSV - 4 bit temporary storage location for FPS: this variable gets 
Gecremented every VDP interrupt, and is reloaded from FPS. 0 to 15 (0 =) 16) 


NLEN - 8 bit note duration for a fixed frequency note: 0 to 255 (0 =) 256) 
8 bit number of steps for a swept frequency note: 2 to 255 (0 =>256) 


Note durations: 


Fixed frequency -. NLEN * 16.?ms 

Swept frequency - CCNLEN -1) ® FPS) ¢ initial FPSV] ® 16.?ms 
guration ist step = initial FPSV ® 16.7ms 

guration al! others = FPS * 16.7?ms 


* Attenuation sweeps 


Volume attacks and decays can be thought of as attenuation sweeps: a sweep from 
low to higher volume is an attack, a Sweep in the other direction is a decay. 
Attenuation sweeps are created in a similiar fashion to the frequency sweeps 
described above, the primary difference being that attenuation sweep parameters 
don't take on & bit values. The full volume Tange for the attenuation 

registers on the 76489 chip is © (ON) to 15 (OFF), 60 step sizes and number of 
Sweep steps greater than 4 bits aren't generally useful. 


Just as in the case of a frequency swept note, attenuation sweeps have four 
parameters that describe the sweep: 1) the starting attenuation, 2) ASTEP, a 
Signed step size, i.e., a delta attenuation that is periodically added to the 
current attenuation, 3) the prescaler value (APS) which determines the length 
of time at any one attenuation step, and 4) ALEN, the number of steps in the 
Sweep. 


The prescaler parameters, APS and APSV, are the same size (4 bits) and mean 
exactly the same thing as their frequency counterparts. ALEN, the number of 
steps in the sweep, is only 4 bits (compared to an FLEN of 8 bits), but 15 
steps of even the smallest step size (+/-1) can Sweep a generator from full on 
to full off. ASTEP, in order to squeere it into a nibble, has been limited to 
a 4 bit signed number (3 bits data, 1 bit sign). This gives a range of step 
values from 1 to 7, =-1 to -8. This shouldn't be too limiting, since most 
attenuation sweeps are implemented with the smallest step size. 


NOTE: Recall that, as far as SND_MANACER is concerned, the Jength of a note is 
Getermined, directly or indirectly, only by NLEN, a timer/counter that is 
Gecremented during FREQ_SWEEP; i.e., the duration of a note is independent of 
what is happening to its attenuation. Therefore, the programmer should take 
care to see that an attenuation sweep isn't inadvertently created that ramps 

the volume down to off before SND_MANAGER, through NLEN, has decided that the 
note is over. However, since ATN_SWEEP simply leaves the attenuation alone 
once it's finished a sweep, the independence of attenuation sweep length and 
note length may be put to good use: e.g., a sforrando can be accomplished by 
making an attenuation sweep (to a still audible volume) end before the rest of 

the note. 


ALEN, like NLEN for a frequency sweep, is the number of steps in an attenuation 
Sweep and can take on values from 0 to 15. However, since a “step” consists of 
atone (which may be frequency swept) played at a fixed attenuation level, a 

Sweep of 1 step doesn't make sense. ALEN values, then, should Tange from 2 to 
15. An ALEN value of 0 causes a sweep of sixteen steps (NOTE: ATN_SWEEP “wraps 
around" at 0 and 15, i.e., subtracting 1 from 0 results in 15, and adding 1 to 

15 results in 0). 
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The duration of an attenuation sweep can be calculated as follows: 


Guration entire Sweep = [((ALEN -1) ® APS) ¢ initial APSV] * 16.?ms 
duration ist step = initial APSV ® 16.7ms 
duration all others e« APS * 16.?ms 


Attenuation sweep parameter ranges: 


ALEN: 4 bit number of steps in an attenuation Sweep; can take values from 2 to 
15 (0 =) 16 steps). 


ASTEP: ASTEP is the 4 bit signed (two's complement) size of a step in an 
attenuation sweep; can take values from 1 to 7, -1 to <8. 


APS: 4 bit attenuation prescaler, used with ALEN to determine the length of a 
frequency sweep: 0 to 15 (0 =) 16). 


APSV: 4 bit temporary storage location for APS; this variable gets decremented 
every VDP interrupt, and is reloaded from APS: 0 to 15 (0 => 16) 


Descriptions of each of the siz note types follow: 
* Rests 
See Figure 4. 


byte 0: BS set indicates a rest, to be played on CH# in B? - Bé 
duration = (B4 - BO) ® 16.%ms, can take values 1 to 31 


® Type 0: Fixed frequency, fixed attenuation 
See Figure 4. 


byte 0: header, CH# in B7 - Bé, note type = 0 in Bi - BO 
byte 1: least significant 8 bits of the 10 bit frequency data (constant) 
byte 2: MSN = 4 bit ATN data (constant throughout the note) 

LSN = 0 O FO Fl, the top 2 bits of the frequency data (constant) 
byte 3: NLEN, duration of the note = NLEN ® 16.7ms 


* Type 1: Swept frequency, fixed attenuation 
See Figure S$. 


byte 0: header, CH® in B7 - Bé, note type = 1 in Bi - BO 
byte 1: least Significant 8 bits of the initial 10 bit frequency data 
byte 2: MSN = 4 bit ATN data (constant throughout the note) 
LSN = 0 O FO Fi, the top 2 bits of the initial frequency data 
byte 3: . NLEN, number of steps in the frequency sweep, 1 to 255 (0 =) 256) 
byte 4: FPS : FPSV, prescaler reload value and initial FPSV 
byte 5: FSTEP, sweep step size, 1 to 127, -1 to -128 


* Type 2: Fired frequency, swept attenuation 
See Figure 6. 


byte 0: header, CH# in B? ~ Bé, note type = 2 in B1 - BO 
byte 1: least significant 8 bits of the 10 bit frequency data (constant) 
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byte 2: MSN = 4 bit ATN data (initial value) 
LSN = 0 O FO Fi, the top 2 bits of the frequency data (constant) 
byte 3: NLEN, duration of the note = NLEN * 16 7ms 
byte 4: ALEN ! ASTEP 
ALEN = number of steps in the attenuation sweep 
ASTEP = step size, 1 to 7, -1 to <8 
byte 5: APS : APSV, prescaler reload value and initial APSV, 1 to 15 (0 =) 16) 


* Type 3: Swept frequency, swept attenuation 
See Figure 7. 


byte 0: header, CH# in B7 - Bé, note type = 3 in Bi - BO 
byte 1: least significant 6 bits of the initial 10 bit frequency data 
byte 2: MSN = 4 bit ATN data (initial value) 

LSN = 0 0 FO Fi, the top 2 bits of the initial frequency data 


byte 3: NLEN, number of steps in the frequency Sweep, 2 to 255 (0 =) 256) 
byte 4: FPS | FPSV, prescaler reload value and initial FPSV, 0 - 15 (0 =) 16) 
byte §: FSTEP, sweep step size, 1 to 127, -1 to -128 

byte 6: ALEN : ASTEP 


ALEN = number of steps in the attenuation sweep 
ASTEP «= step size, 1 to 7, -1 to -8 : 
byte 7: APS | APSV, prescaler reload value and initial APSV, 1 to 15 (O =) 16) 


* Noise notes: special case Type 2 notes 
See Figure 8. 


Noise notes are notes that are played on the sound chip noise generator (CH#0). 
They are stored in ROM as a special case of a Type 2 note, fixed frequency and 
Swept attenuation. They consist of white noise with superimposed attenuation 
decay, which creates a percussive effect, such as a snare drum note. 


Instead of frequency information, noise notes are stored with three bits of 
noise control data: FE NFO NFi (see TI data sheets 76489), which remain 
constant throughout the note. Experimentation with various values can result 
in credible percussion effects. 


NLEN, as is the case for a regular Type 2 note, directly determines the 
duration of a noise note. 


The sound chip noise generator is unlike the other generators in that sending 

it redundant data (i.e., the same data that it has stored in its internal 

registers) has an audible effect on its output. In particular, whenever 

control data, redundant or not, is sent to the noise generator, its internal 

shift register is reset, causing a short pop or click to be heard. This isn't 
annoying on an occasional basis, or when a new noise starts, but remember: 
PLAY_SONCS is sending data to all four channels every 146.7ms. This would cause 
a noticeable lack of "whiteness" in the noise generator's output. 


PLAY_SONCS avoids this problem by referencing a dedicated CART RAM location, 
SAVE_CTRL (see Figure 9) each time before it sends contro] data to the noise 
generator. SAVE_CTRL contains the contro] data that was output to the noise 
generator the last time through PLAY_SONCS. If the noise contro! data in the 
pointed to song data area = SAVE_CTRL, PLAY_SONCS doesn't send it out again. 
If there is new data to be sent, that data is output and SAVE_CTRL is updated. 


11 
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byte 0: 
1: 


byte 


byte 2: 
3: 


byte 


byte 


header, CH#0 in B? - Bé, note type = 2 in Bi - BO 

MSN = 4 bit ATN data (initial value) 

LSN = 0 FB NFO NFI, noise contro! data 

NLEN, é@uration of note: NLEN * 16.?ms 

ALEN ! ASTEP 

ALEN © number of steps in the attenuation sweep 

ASTEP = step size, 1 to 7, -1 to <8 

APS : APSV, prescaler reload value and initial APSV, 1 to 15 (0 =) 16) 
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OPERATING SYSTEM ROUTINES 


INIT_SOUND 
Contains ENTRY POINT: ALL_OFF 


INIT_SOUND, usually called right after power on, turns off the sound 
Generators, initializes the CART RAM locations to be used as song data areas, 
and sets up the four channe! data area pointers. Specifically, it: 


1) directly turns off all four sound generators. 

2) initializes PTR_TO_LLST_OF_SND_ADDRS, a dedicated 16 bit CPU RAM pointer 
which other sound routines expect to contain the base address of a list in 
CART ROM (called LST_OF_SND_ADDRS) of the starting addresses of each 
song's data area and note list. The address of LST_OF_SND_ADDRS is passed 
to INIT_SOUND in HL. 

stores the sound-inactive code (OFFH) into byte 0 of n song data areas. n 

is passed in B and = the total number of song data areas used by the game. 

4) stores an end of data area code (00) following the last data area. 

5S) sets the four pointers to the data areas for the songs to be played on 


3 


~~ 
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each channel, PTR_TO_S_ON_x (x = 0-3), to a dummy inactive area (DUM_AREA, 


which is actually a single OFFH byte within INIT_SOU). 
6) sets SAVE_CTRL to an initial value of OFFH 


INPUT: n 
TYPE: 8 bit constant 
PASSED: in B 


DESCRIPTION: number of song data area used by the game 


INPUT: LST_OF_SND_ADDRS 

TYPE: 16 bit address 

PASSED: in HL 

DESCRIPTION: LST_OF_SND_ADDRS is the base address of a list of the starting 
addresses of each song's data area and note list. 


OUTPUT: 1) turns off all sound generators 
2) initializes PTR_TO_LST_OF_SND_ADDRS 
3) writes inactive code to byte 0 of n song data areas 
4) stores 00 at end of song data areas 
5) sets the 4 channel song pointers to the inactive DUM_AREA 
6) sets SAVE_CTRL to OFFH 


ALL_OFF 


ALL_OFF directly turns off all four sound generators, but does nothing to any 
song data areas or the 4 channel data pointers. 


INPUT: none 


OUTPUT: turns off all sound generators 
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JUKE_BoOxX 


JUKE_BOX is called to start a song. Using a song number passed in B, JUKE_BOX 
loads the data for the song's first note into the appropriate song data area 

(the address of the area is found by using the song number as an index into the 
LST_OF_SND_ADDRS table). It also formats the data area's header and sets up 
the next note pointer. If the song-is a special sound effect, its next note 
pointer is set to the address of the speciai effect routine. The next time 
PLAY_SONCS is called, that song's first note will be processed (thereby 
truncating whatever song had been “playing” in that data area), and the song 

will have started. 


Since starting a new song may have altered the priority structure within the 
song data areas, JUKE_BOX also calls UP_CH_DATA_PTRS to modify the channe! data | 
pointers accordingly. | 


If JUKE_BOX is called with a song number of a song already in progress, it 
returns immediately (i.e., it doesn't restart the gong). 


INPUT: song number to be started 
TYPE: 8 bit constant, 1 to 61 
PASSED: in B 


CALLS: PT_IX_TO_SxDATA, LOAD_NEXT_NOTE, UP_CH_DATA_PTRS 


OUTPUT: 1) moves the song's first note data to the appropriate song data area 
1) formats byte 0 header of the song's data area 
2) points next note pointer in data area (bytes 1&2) to address of 
first note in song, or address of Special sound effect routine 
3) updates the channel data pointers on basis of song priorities 
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SND_MANAGER 


SND_MANAGER should be called every VDP interrupt (every 16.7 ms). It assumes 
that the song data areas are stored contiguously in a data block beginning with 
_the data area assigned to song number one. For each data area, SND_MANACER, or 
routines which it calls, processes the appropriate timer and sweep counters and 
modifies the frequency and attenuation data accordingly. If the Gata area is 
assigned to @ special effect, SND_MANACER Simply calls that effect, and doesn't 
modify any data. When a note is finished, SND_MANAGER, using the data area's 
next note pointer, woves data for the next note of the song into the area and 
fills in keys bytes within the area to allow Proper processing of the data area 
by the sweep routines it calls (PREG_SWEEP and ATN_SWEEP). (SND_MANAGER 
considers a note finished when its frequency duration timers have timed out; \ 
see the descriptions of the FREQ_SWEEP and ATN_SWEEP routines) A special 
effect is responsible for deciding when its over and initiating the next note 

in the song. 


After the operations upon a data area have been performed, the channel data 
area pointers (PTR_TO_S_ON_x) may be updated (see Gescription of 
UP_CH_DATA_PTRS in "UTILITIES" section). 


If SND_LMANAGER reads a header byte (in CART ROM) that has bits 3&4 set, 
indicating repeat song, it will start the song again by reloading the first 

note in the song, using the SONGNO portion (B5-B0) of byte 0 in the song's data 
and the LST_OF_SND_ADDRS to find it. 


SND_MANAGER does not output the modified frequency and attenuation data. 
PLAY_SONGS is usually called just before SND_MANACER to do this. 


Special codes in byte 0 of the song data area indicate: 


OFFH - data area inactive, do no processing, do not modify channel 
data area pointer 

BS-BO = 62 - &@ special effect is to be played; SND_MANAGER calls the effect 
routine 

OOH - end of song data areas (SND_MANACER processes data areas until 


it sees 0 in byte 0) 


NOTE: Song number 1 MUST use the first data area in the block of song data 
areas. 


INPUT: none 
CALLS: PROCESS_DATA_AREA, PT_IX_TO_SxDATA 


OUTPUT: 1) decrements song duration and sweep timers 
2) modifies swept frequency and attenuation values 
3) calls special effects routines where necessary 
4) restarts the song if indicated 
S) may update the channel data area pointers (PTR_TO_S_ON_x®) 
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PLAYSONCS 


PLAY_SONCS takes the frequency and attenuation data pointed to by the four 
channel data area pointers (PTR_TO_S_ON_x) and outputs it to the four sound 
chip generators. Action is taken on the basis of the each data area's byte 0: 


1) If the pointed to data area is active, the frequency and attenuation data 
are sent to the channel indicated by B7-Bé (CH) of byte & of the pointed 
to data area. 

2) If byte 0 is OFFH (inactive), the channel to which that pointer is 
Gedicated is sent the OFF attenuation code. 

3) If CHE = O (noise), the attenuation data is output. If there is no new 
noise control] data to be output (determined by checking dedicated CART M 
location SAVE_CTRL), no control data is sent out. Otherwise, the new 
control data is output and SAVE_CTRL is updated. 


INPUT: none 


OUTPUT: through SOUND_PORT, 
1) current freq and atn data is output to each tone generator, if 
song/effect on that channel is active 
2) noise generator is sent current atn data, and contror data, if new 
3) modifies SAVE_CTRL if necessary 
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FREQ_SWEEP 


FREQ_SWEEP is used by SND_MANACER and special effects routines to create 
frequency sweeps. It Operates upon frequency data stored within « song data 
area, and is normally called (by SND_MANACER or a special effect routine) once 
every VDP interrupt (16.?ms). The start of the data area (address of byte 0) 

is passed in Ix. . . e 


FREQ_SWEEP assumes data has been stored as fellows (names which may be used to 
describe the various bytes or byte segments within the data area are indicated; 
see Figure 1): 


byte 3: the least significant 8 bits of that note's frequency (F2 - F9) ‘ 
byte 4: top 2 bits of that note's frequency: B1 = FO, B2 e« Fi 


byte 5: NLEN - determines the note's duration: 
1) if frequency is to be swept, NLEN = number of steps in the sweep. 
2 to 255 (0 =) 286) 
2) if fixed frequency, NLEN ® 16.7 ms = duration of the note: 
1 to 255 (0 &> 256) . 


byte 6: FPS ! FPSV - frequency sweep duration prescaler: 
FPS = prescaler reload value: 0 to 15 (0 ») 16) 
FPSV @ temp storage nibble for FPS: init ROM value, 0 to 15 (0 =) 16) 
duration of sweep (& note) = CCCNLEN-1) ® EPS) + initial FPSV) * 16.?ms 
Curation ist step = initial FPSV ® 16.?ms 
duration all other steps = FPS * 16.?ms 


byte 7: FSTEP - frequency Sweep step size: signed 8 bit number, two's 
complement: 1 to 127, -1 to -128 
if FSTEP » 00, frequency is not to be swept, but NLEN is decremented 
each time called 


Parameter limitations: 

1) In a frequency sweep, a “step" consists of a single fixed frequency tone; 
therefore, the minimum number of steps a frequency sweep can have is two 
(otherwise the frequency wouldn't have “swept"). 

2) If a note is to be frequency swept, FSTEP must not be 0. 

3) The minimum length fixed frequency note has NLEN e« 1. 

4) Maximum NLEN 0, which is equivalent te 256. 


FREQ_SWEEP returns with the Z flag SET if the note (swept or fixed) is over, 
RESET if the note is not over. (PROCESS_DATA_AREA decides that a note is over 
when FREQ_SWEEP returns with the Z flag set) 


INPUT: 16 Bit address of a song data area in CPU RAM 
PASSED: - in 12 
DESCRIPTION: FREQ_SWEEP Operates upon frequency data within this song Gata area 


OUTPUT: 1) duration and sweep counters are decremented 
2) freq data in bytes 364 is modified if note is freq swept 
3) returns with Z flag SET if note over, RESET if note not over 
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ATN_SWEEP 


ATN_SWEEP is used to create attenuation sweeps. It Operates upon attenuation 
data stored within a song data area, and is nermally called (by 
PROCESS_DATA_AREA or a special effect routine) once every VDP interrupt 
(16.7ms). The start of the data area (address of byte 0) is passed in IX. 


; e 
ATN_SWEEP assumes data has been stored as follows ( see Figure 1): 
byte 4: ATN - the MSN = 4 bit attenuation 


byte 8: ALEN ! ASTEP - no-sweep code or sweep length and step size: 
1) i6 byte 8 = 00, ATN is not to be swept and counters aren't chanbed 
2) af byte 8 non gero, attenuation is to be swept: 
a) ALEN es number of steps in the sweep: 1 to 15 (0 =) 16) 
b) ASTEP = sweep step size: 1 to 7, -1 to -8 (signed, 4 bit two's 
complement) . 


byte 9%: APS ! APSV - attenuation sweep duration prescaler: 
1) if attenuation is not swept, byte 9 is not used by ATN_SWEEP 
2) if attenuation is to be swept: 
APS @ prescaler reload value: 1 to 15 (0 =) 16) ® 
APSV = temp storage nibble for APS: init ROM walue, 1 to 15 (O =) 16) 
Guration of swept attenuation part of note = 
C(CALEN - 1) ® APS) « initial APSV] ® 16.7 ms 
duration ist step = initial APSV * 16.7?ms 
duration all other steps = APS *® 16.?ms 


Parameter limitations: 

i) In an attenuation sweep, a "step" consists of a tone (swept or not) played 
at a fixed attenuation level; so, the minimum number of steps an 
attenuation sweep can have is two (otherwise the attenuation wouldn't have 
“swept"). Therefore, the minimum ALEN value is 2 (0 =) 16) 

2) If a note is to be attenuation swept, byte & must not be 00. 

3) The absolute value of ASTEP must be ) = 1. 


If byte 8 is 00, ATN_SWEEP returns immediately with Z flag SET (the sweep is 
over or the note was never swept), and doesn't modify any counters. When a 
sweep finishes, ATN_SWEEP sets byte & to 00 and returns with the Z flag SET. 

If a sweep is in progress, ATN_SWEEP returns with the Z flag RESET. (NOTE: 
PROCESS_DATA_AREA decides that a note is over when FREG_SWEEP returns with Z 
set: the length of a note has nothing to do with when its attn sweep is over) 


INPUT: 16 bit address of a song data area in CPU RAM 
PASSED: in IZ 
DESCRIPTION: ATN_SWEEP operates upon frequency data within this song data area 


OUTPUT: 1) duration and sweep counters are decremented if sweep in progress 
2) atn data in byte 4 is modified if note is atn swept 
3) RETs C SET, byte 8 = 0 if sweep is over or note was never swept 
RETs C RESET if sweep in progress 


COLECOVISION SOUND USERS' MANUAL Page 19 
PROCESS_DATA_AREA 


PROCESS_DATA_AREA ts called by SND. —MANACER. For an active data area (address 
of byte 0 passed in IX), PROCESS —DATA_AREA modifies the timers, Sweep counters, 
frequency, and attenuation data by calling FREQ SWEEP and ATN_SWEEP. If a note 
finishes during the current pass through PROCESS —DATA_AREA, the next note in 
the song is examined and its data ig loaded into the data area (calls 
LOAD_NEXT_NOTE). Then, in order to maintain the song data &rea priority 
structure, the CH@ ! SONGNO of the newly loaded note is compared to the 

CH : SONGNO of the previous note: if there is a difference, UP_CH_DATA_FPTRS is 
called to adjust the channel data area pointers in response to the change 

caused by loading the next note. 


‘ 
If the data area is being used by a special sound effect, PROCESS —_DATA_AREA 
calls the sound effect routine whose address is stored in bytes 1&2 of the data 
area (the actual address called is routine + 7: see discussion of special sound 
effects). 


If the data area is inactive, PROCESS DATA_AREA returns immediately (no 
Processing occurs). 


INPUT: address of byte 0 of a song data area 
PASSED: in IX 


CALLS: ATN_SWEEP, FREQ_SWEEP, LOAD_NEXT_NOTE, UP_CH_DATA_PTRS, AREA_SONC_IS 


OUTPUT: 1) if active, modifies song data area's timer, freq, and atn data 
, 2) loads the next note's data when a note is finished 
3) if special sound effect routine using data area, calls it 
4) when necessary, updates the channel data area pointers 
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LOAD_NEXT_NOTE 


Called by PROCESS_DATA_AREA and JUKE_BOY, LOAD_NEXT_NOTE examines the nert note 
to be played in a data area (address byte © passed in IX) and moves its data 
_ into the area. It fills in bytes (e.g., to indicate swept or not swept) where 
appropriate, based upon note type. If the next "note" is a special sound 
effect, its address is saved in bytes 162 and the address of the routine « 0 is 
called, with the address of the note to follow the effect passed in HL and 
SONCNO passed in A. This will cause the special effect routine to save both 
these values. Then, the special effect routine + 7 is called, which allows the 
routine to initialise the song data area for the first pass through PLAY_SONCGS. 
(see discussion of special sound effects) 

\ 
Prior to moving the next note data, LOAD_NEXT_NOTE saves the data area's byte 0 
(CH® | SONGONO) and stores the song inactive code (OFFH) there. The last thing 
LOAD_NEXT_NOTE does is restore byte 0, loading CH# with the CH@ | SONGNO of the 
new note (usually the same as the old note). If the new note is a special 
sound effect, 62 is returned as the SONCNO part of byte 0. 


INPUT: address of byte 0 of a song data area 
PASSED: in Ix P 


OUTPUT: 1) sets up song data area with data from next note to be played 

2) for next note = special sound effect, calls the effect twice, first 
with the address of the following note in the song and the song's 
SONGNO, and then once more to allow the effect to initialize the 
song data area 

3) if next note is "normal", loads CH® ! SONGNO in byte 0 with 
CH# : SONGNO of new note 

4) returns with byte 0 = OFFH if song over, SONGNO ® 62 if next note is 
a sound effect 
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UTILITIES 


The following are 0/5 otility routines, used by the main O/S sound programs, 
that may be of use to the Cartridge programmer: 


#e2* AREA_SONG_I8 ane 

® 
The address of byfe 0 of a song data area is passed in IZ. The song number of 
the song using that area is returned in A (OFFH if inactive). If a special 
effect was using that area, 62 is returned in A and HL is returned with the 
address of the Special sound effect routine. 


®* UPATNCTRL eee ' 


Perform single byte update of the snd chip noise control register or any 
attenuation register. IX is passed pointing to byte 0 of a Song data area, MSN 
register C = formatted channel attenuation code. 


Ske UPFREQ een 

Perform double byte update of a sound chip frequency register. IX is passed 
pointing to byte of a song data area, MSN tegister D = formatted: channel! 
frequency code. 

Bee DECLSN zeae 

Without affecting the MSN, decrement the LSN of the byte pointed to by HL. HL 
remains the same. 


RET with Z flag set if dec LSN results in 0, reset otherwise. 
RET with C flag set if dec LSN Tesults in -1, reset otherwise. 


Rua DECMSN RAR 

Without affecting the LEN, decrement the MSN of the byte pointed to by HL. HL 
remains the same. 

RET with Z flag set if dec MSN results in 0, reset otherwise. 

RET with C flag set if dec MSN results in -1, reset otherwise. 

See MSNTOLSN eee 


Copy MSN of the byte pointed to by HL to the LSN of that byte. HL remains the 
sane. 


Bae ADDEI6 aan 

Adds 8 bit two's complement signed value passed in A to the 16 bit location 
pointed to by HL. Result is stored in the 16 bit location. 

eee PT_IX_TO_SeDATA aan 


A SONGNO is passed in B. PT_IX_TO_SxDATA returns with 1x pointing to the song 
Gata area which is used by that SONGNO. 
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ee* UP_CH_DATA_PTRS #28 


UP_CH_DATA_PTRS adjusts each channel data pointer to point to the highest 
priority (ordinal last) song data area that uses that channel. It is called 
whenever a change has been made to a song data area that requires modification 
of the channe! data pointers. 


All @ channel data pointers (PTR_TO_S_ON_z) are initially poimted to a dummy 
inactive area, DUM_LAREA. Then, moving in order from the first data area to the 
last, CH@ in byte 0 of each data area is examined, and the corresponding 

channel data pointer is pointed to that data area. Thus, by the time the 

routine is done, each channel data pointer is pointing to the last active data 
area that contains data to be sent to that channel. If none of the active dat 
areas used a particular channel, then that channel remains pointing to DUM_AREA 
(and therefore its generator will be turned off next time through PLAY_SONGS). 


ae LEAVE_EFFECT xe8 


LEAVE_EFFECT, called by a special sound effect routine when it's finished, 
Testores the SONGNO of the song to which the effect belongs to BS - BO of byte 
0 in the effect's data area, and loads bytes 1 & 2 with the address of the next 
note in the song. The address of the 1 byte SONGNO (saved by the effect when 
it was first called) is passed in DE. The 2 byte address of the next note in 
the song, also saved by the effect, is passed in HL. IX is assumed to be 
pointing to byte 0 of the data area to which the song number is to be restored. 
Bits 7 & 6 of the saved SONGNO byte are not stored into byte 0, and therefore 
may be used during the course of the effect to store any useful flag 
information. 


SPECIAL SOUND EFFECTS 
* Sound effects as notes within a song 


Sounds which do not fit one of the siz categories of "normal" musical notes can 
be created and played throughout the course of a song as "special effect" 

notes. Unlike normal musical notes, which are stored in ROM as tables of 
frequency/control and attenuation data, a special effect's data are determined 
algolrithmically by a custom routine written by the cartridge programmer. 

Special effect notes can also be used to generate sounds that could have been 
comprised of many normal notes, but which are more efficiently (in terms of ROM 
Space used) computed by a short program. 


These notes use the same song data area as the song within which they are 
contained, and they are stored in the song's ROM note list with a one byte 
header as are norma! notes. However, the bytes following the ROM header do not 
contain data to be directly loaded into the song data area. The header (see 
Figure 2), which specifies the channel upon which to play the effect (which is 
usually the same as the channel used by the rest of the notes in the song), is 
followed by a two byte address of a routine written by the cartridge programmer 
which will be called every 16.7ms by PROCESS _DATA_AREA. When called, this 
special effect routine should compute data values and store them at the 
appropriate locations within the song data area. (In fact, many effect 

routines may call the O/S routines FREQ_SWEEP or ATN_SWEEP, which also require 
that data be ordered appropriately within a song data area) This computed data 
will then be output on the next pass through PLAY_SONCS (assuming that this 
song data area has the highest priority of any data area using the same 

channel). 
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Variables required by the effect which will not be output may be stored 
wherever the programmer desires. Free locations within the song's date area 
might as well be used for effect variable storage, since the entire ten byte 
area is reserved for the song anyway. If no free locations exist within a data 
area, which would be the case if an effect required both frequency and 
attenuation to be swept, the effect can store the temaining needed variables 
wherever convenient. 7 e 


In order to interact properly with the O/S sound routines, each special effect 
routine must conform to a certain format. A description of that format, and 
how an effect interacts with the O/S routines, follows: 


WHEN AN EFFECT BECINS - When loading a new note, if LOAD_NEXT_NOTE see that 
the note to be loaded is a special effect: 


1) It stores in byte 0 of the song's data area the effect's CH@ and a SONGNO of 
62. SONCNO = 62 is used later by PROCESS_DATA_AREA te detect the fact that an 
effect is using the data area. 


2) It then takes the address of the special effect routine (lets's call it SFX) 
from ROM and puts it into bytes 162 (NEXT_NOTE_PTR). 

3) LOAD_NEXT_NOTE then calculates the ROM address of the header of the next 
note in the song, stores that address in HL, puts the song's SONCNO in A, and 
calls SFX + 0. In every special effect routine at SFX « 0, there MUST be the 
following code which saves the two passed values (see Figure 9): 


SFX: LD (SAVE_z_NNP),HL 
LD (SAVE_x_SONGNO),A 
RET 
SFX+?7: code for sound effect starts here 


where SAVE_s_NNP is a two byte location used by all the sound effect notes in 
the current song to save the address of the next note in the song, and 
SAVE_x_SONGNO is the address of a byte where the song number is saved. The 
programmer may put SAVE_z_ NNP and SAVE_= SONGNO wherever desired, including 
somewhere within the song data area. 


Thus, calling SFX + 0 allows each effect routine to save the next note's 
address and the song's SONGNO. ; 


iST PASS THROUGH EFFECT - After calling SFX « 0, LOAD_NEXT_NOTE ecalls SFX + 7 
for the first pass through the body of the routine. At this location, there 

should be code which initializes the appropriate bytes within the song data 

area, as the next pass through PLAY_SONGS, subject to the data area priority 
system, will output this initial data in norma! fashion. 


As will be seen below, this same location (SFX + 7) will be called every 16.7ms 
by PROCESS_DATA_AREA to modify the data within the area. Therefore, the code 
at SFX + 7 must know which pass is in effect, so that the song data area will 

be initialized only on the first pass. A convenient way of Going this is to 

test bit 7? of SAVE_=z_SONCNO, the byte which contains the saved song number. 
On the Ist pass through the effect, bit 7 (and bit 6) will be zero, since the 
largest possible SONGNO (62) would not set this bit. If bit 7 is zero, then, 

code to initialize the data area can be executed and bit 7 reset to prevent re- 
initialization. TI.e., 
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SFX47: LD HL, SAVE_s_SONGNO 


BIT 7, CHL) 
JR NZ,NOT_PASS_1 
SET 7, CHL) ito prevent further passes thru inits 
er sinitialize bytes within the data area here 
RET sto LOAD_NEXT_NOTE 
NOT_PASS_1: .... icode for pass 2 or greater starts here 


PRIORITY UPDATE - After Calling SFX + 0 and SFX « 7, LOAD_NEXT_NOTE will return 
to PROCESS_DATA_AREA, which checks to see if loading a new note has caused a 
change in either the channel used by the song (this happens with noise notes 

within a musical song) or the song number. If a change has occured, \ 
UP_CH_DATA_PTRS will be called, which updates the data pointers on the basis of 
priority within the block of song data areas (see Gescription of this routine 

in the preceeding "UTILITIES" section). Since a special effect note will cause 

a change in the song number (from whatever it was to 62), UP_CH_DATA_PTRS will 
always be called whenever an effect note is loaded. 


SECOND PASS OR GREATER - The next time PROCESS_DATA_AREA is called (from 
SND_MANAGER), which will be 16.?ms after PLAY_SONCS has sent out the effect's 
initial data, it will detect the fact that an effect is using the song data 

area (by seeing a SONGNO of 62) and will JUMP to SFX + 7, rather than calling 

the frequency and attenuation Sweep routines as it would for a norma! note. 

This will result in the first pass through the part of the body of the effect 

routine that actually does computation and adjusts the data values within the 

Gata area. When the effect routine has completed its modifications to the data 
area and performs a RET, control is transferred back to SND_MANACER, which then 
moves on to the next song data area to be Processed. 


This process will be repeated every 16.7ms until the effect routine itself 
Gecides that it's over and takes action to load the next note in the gong. 


WHEN AN EFFECT IS OVER - Prior to performing a RET, the effect routine must 
Gecide whether the effect note has finished. If it has, NEXT_NOTE_PTR within 
the data area must be set to the address of the next note in the gong and 

SONGNO must be restored to byte 0. This can be done by calling the O/S routine 
LEAVE_EFFECT which does this. The address of SAVE_x_NNP must be passed in HL 
and the address of SAVE_z_SONCNO must be passed in DE. Finally, the effect 
should JUMP to EFXOVER, a location within PROCESS_DATA_AREA which would 
normally be reached once a note is over. The code there takes care of loading 
the next note in the song. Thus, the final code of each effect routine will 

look as follows: 


RET if effect not over 


LD HL,(SAVE_x_NNP) HL := addr next note in song 

LD DE,SAVE_x_SONCNO iDE := addr saved song number 

CALL LEAVE_EFFECT ito restore them to bytes 0 - 2 in data area 

JP EFXOVER sin PROCESS_DATA_AREA to load song's next note 


The entire above described sequence is summarised in Figure 9. 


® A sound effect as a single sound 


A stand alone sound effect can be implemented within the Previously mentioned 
structures simply by creating a single note song. The Single note is the effect 
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and would be followed by an end of song code (or repeat code if you wish the 
effect to go on forever). 


Many stand alone effects may want to use more than one tone generator channel: 
@.g., @ special laser sap that momentarily requires all three tone generators, 
or, as is often the case, a white noise effect of particular character that 
Tequires the noise channel! shift rate to be modified by channel three (see TI 
gata sheets). In these cases, the effect's routine will have tommodify data in 
several data areas whenever called. The song data areas used by such effects 
are subject to the normal priority structure. E.g., if you wish a two channel 
effect to temporarily overwrite the harmony and bass lines of a repeating song, 
the effect must have been assigned two data areas of higher priority (ordinally 
later in the block of song data areas). If it is not necessary to maintain any 
underlying songs, an effect can share data areas to conserve RAM space, with’ 
the understanding that, as usual, songs or sounds that share the same song data 
area truncate each other. A multi-channel effect (a chord note, say) may be 
included as a note within a song, but, again, the song data area priority 
structure determines what will finally be heard. 


Providing for a typical game's sound generation needs might require eight song 
data areas: four for an underlying, repeating song(s) (three areas for the 
three tone generators and one for the noise generator used for percussion 
notes), and four for higher priority, occasional sound effects (which would 
temporarily overwrite the repeating songs, but truncate each other). 


® Pseudo code listings of main routines 


The following two pages contain pseudo code descriptions of most of the O/S 
sound routines. Some computational details are not shown, but all jumps, 
calls, returns, pushes and pops are listed. . 


Terminology: 
“:e" is used as the assignment statement, and "(zz)" means the contents of the 
memory location pointed to by zz, where "zz" is HL, IX, etc. 


The structure of each description is as follows: 


#22 name of routine ®2% 
the value expected for passed parameters (if any) 


pseudo code description 

of the routine, uninterrupted 
by blank lines 

RET 


Bue JUKE _ BOX sax 
B © SONGNO to be Started 


PUSH BC 
CALL PT_IX_TO_SeBATA (IX set?) 
Pop BC 
RET if song in progress 
byte 0 := SONCNO 
set WEXT_MOTE_PTR te ist aete in Song 
CALL LOAD_WEXT_NOTE 
CALL UP_CH_DaTa_PTRs 
RET 


BBs PLAY_SONCS ess 


set A fer CHi OFF eade 

wet MSm C fer CHI attenuation 
Bet ASN D fer CHi frequency 
IX :© (PTR_TO_S_ON_1) 


(2a.e., pt IX to byte © data area of Gong fer CH1?) 


CALL TONE _OUT 

set A for CH2 OFF cede 

Set MSW C fer CHZ2 attenuation 
Set MSW D for CH2 frequency 
Ix :@ (PTR_TO_S_ON_2) 


(iie., pt IX to byte © data area eof sang fer CH2) 


CALL TONE_OUT 

set & for CHI OFF cede 

eet MSN C for CHS attenuation 
Get ASN D for CHI frequency 
Ix :© (PTR_TO_S_OW_3) 


(2.@., pt IX to byte O data area of song for CH3) 


CALL TONE _OUT 

Set @ for CHO OFF code 

set MSN C for CHO attenuation 
Ix -e@ (PTR_TO_S_OW_0) 


(a.e@., @t IK to byte © data area of Song for CHO) 


IF area INACTIVE 
turn ef¢ CHO 
ELSE 
CALL UPATNCTRL (send current atn? 
Set LSN A for current etrl data 
IF current ctrl data diff free last 
Peload SAVE CTRL 
CALL UPATNCTRL (send new etrl) 
ENDIF 
ENDIF 
RET 


Bez SND_MANACER Baz 


CALL PT_IX_TO_SsDATA, gang @1 
Loop 
RET 47 end of song data areas 
CALL PROCESS DATA _@REA 
pt IX to byte O mexrt song data area 
REPEAT LOOP ‘ 


BEE PROCESS DATA _AREA BBE 
IX © addr byte 0 of a song data area 


CALL AREA _SOWC_IS 
REY 1¢ ares INACTIVE 
IF SOWGNO © 62 
dP SFX47 (RET free SFX) 
EmprIe 
CALL AYW_SWEEP 
CALL FREG_ SWEEP 
IF mete ever 
EFXOVER: PUSH CHE ! SONCNO mete just ever 
CaLlL LOAD_WEXT_MOTE 
POP CHE : SONCNO note just ewer 
IF CKe + SONGNO newly loaded note not © 
CHe : SONCNO note just over 
CALL.UP_CH_DATA_PTRS 
ENDIF 
EwDIr 
act 


BER LOAD_WEXT_WOTE ez 
IX © addr byte 0 of @ Bong data area 

byte © = CHE (er 00) |: SONGNO 

(SFX © addr of @ Special effect note's routine) 


PUSH 0 0 : SONGNO (CHE net pushed) 
deactivate area ibyte 0 -© FF) 
A :© (MEXT_WOTE_PTR) (header mew ROM note) 


CASE header type af 
Lirest: 
PUSH header ef now ROM note 
Get WEXT_WOTE_PTR for mgxt note in song 
{4.e@., the nate after this new nete) 
Set bytes in seng data area: 
ATN :@ off 
WLEN :@ S bit rest duration 
FSTEP :© © (i.0., no freq sweep! 
ASTEP := 0 (ne atn sweep! 
J? MODBO 
Ziend ef song: 
IF end repeat 
POP BC (B :© SONGNO! 


CALL SUKE_BOX to reload ist neve of this Seng 


RET (te PROCESS DaTAa_@REA) 
ENDIF 
PUSH inactive code 
JP mODBO 
Jispecial effect: 
POP YY (IY :© SONGNO) 
PUSH IY to put SONGNO bact on stact 
PUSH header now ROM note - 
Set MEXT_WOTE_PTR, bytes 162, te SFX 
(address special effect routine) 
set DE to SFX 
HL :© addr mext mote in song 
(4.@, the mote after this new effect note?) 
PUSH TY, POP AF (A -= SONGND) 
PUSH DE, POP TY (IY :@ SFX) 
DE := PaSS1, PUSH DE 
oP (IY), d.e., “CALL (IYS*, RET to Passi 
(SFX saves SONCNO & addr next note) 
Passi: Ivy :e IY ¢7 
DE := MODBO, PUSH DE 
oP IIY), f.e., “CALL (2¥47)°, RET te MODBO 
(SFX47 loads initial effect data) 
4imoreal aste: 
CASE note type 
OIMEXT_WOTE_PTR :© adr song's art note 
@ove J bytes ROM note data to RAM 
FSTEP :© 0 (no freq sweep) 
ASTEP :2© 6 (ne ata sweep) 
gR MODBO 
TINEXT_WNOTE_PTR :© adr song's art note 
@ove S bytes ROM note data to Ran 
@STEP :© O (no ath sweep? 
Z)NEXT_NOTE_PTR -@ adr seng's nxt note 
@ove S bytes ROM note data te Aan 
FSTEP :© 0 (no freq sweep) 
gR MODBO 
SIWEXT_WOTE_PYR :© adr song's art note 
ecve 7 bytes ROM note data to RAM 
ENDCASE 
ENDCASE 


MODBO: PUSH Ix 

POP HL to point to byte 6 

POP AF (A :@ header new note) 

POP BC {B :© SONCNO) 

RET if header is inactive (f.e., Beng ie ever) 
IF header i8 for a special effect 

D :© 62, the SONCNO for al) effect notes 

ENDIF 


byte © :© CHO (froe header new mete) | SONCNO (frse B) 


RET 


@sx INIT_SOUND 82 
iL © addr of LST_OF_@QND_ADDAS 
B= neuber af Song data areas used by gase 


set RAM werd PTR_TO_LST_OF_SND_ABDRS te value passed in HL 
pt HL to byte O in ist Seng data area 

Bi: (HL) :@ dmactive cade (OFFH) 

HL :© WL ¢ 20 

DINZ Bi (eset B areas inactive? 

(HL) :@ end of data area code (0) 

Joad all 4 channel) data area pointers with the 
addr ef @ dunsy inactive area (BUMAREA) 
SAVE_CTRL :© OFFH - 

QLL_OFF: turn eff all 4 generators diroetiy 
RET 


BUMAREA BEFD OF FH 


BEB UP_CH_DATA_PTRS sBs 


PUSH IX te save it : 
eet all 4 ch data ptrs te &@ dussy, imactive area 
CALL PT_IX_TO_S2DATA, song @ 1 

Loop 


IF byte © indicates the end of the song data areas JR DONE 


TF byte © indicates an active area 
Set HL to address of this area's channel data pointer 


(i-e., HL :8 addr PTR_TO_S_ON_O ¢ (CHE this area 8 2)) 


PUSH Ix 
POP DE (DE :© addr byte © this area) 
(HL) :8 E, (CHL41) :© B 
CNDIF 
Ix :8 IX ¢ 10 
ENDIF 
REPEAT LOOP 
DONE POP IX to restore it 
RET 


BRz TONE _OUT BB 


a2z FREG_SWEEP aaz 
~———#_2 addr byte 0 of & Bong data area 


IF FSTEP © 6 mete is net to be swept 
& :3 MLEN 
DEC a 
RET Z Cleave 1¢ mote over, 2 flag SET) 
MLEN :©@ & (stere decresented NLEX) 
RET (mote not over, 2 Fiag RESET) 
ENDIF 
PUSH IX, POP HL (pt ML te byte 6) 
HL :© HL + offset within data area of FPSY 
CALL DECLSN to detresent FPSU 
IF Z #lag SET, FPSV has tieed out 
CALL MSNTOLSN te reload FPSY 
@ -© MLEN 
BEC A 
RET Z Cleave 17 sweep ever with Z flag SET) 
MLEN :8 @ (store decreesnted MLEN) 
point Hi Go FREQ \ 
@ :© FSTEP 
CALL ADDSG16 to add FSTEP toe FREG 
RESET bit 2 in bi byte FREG 
(in ease ef everflow froe addition) 
OR OFFH to RESET Z flag 
ENDIF 
RET 


822 ATN_SWEEP sez 
IX © addr byte 0 of & Song data area 


RET with Z fiag SET if byte @ = 0 
(d.e., mote atn wot to be suept) 
PUSH IX, POP HL (pt HL te byte 0} 
HL :© HL ¢ ef feet within data area of APSY 
CALL DECLSW to decresent APSY 
IF 2 flag SET, @PSV has tised out 
CALL MSNTOLSN to reload APSU 
pt HL te ALEN (@ ef steps im atn swoop) 
CALL DECLSN to decreeent ALEN 
IF Z #lag RESET, sweep not ever get 
ATN :8 ATN ¢ ASTEP 
(4 bait add, averflow ignored) 
OR OFFRK to RESET Z flag 
ELSE 2 flag is SET (sweep is aver) 
byte @ :© 0 to indicate sueep over 
EWDIF 
ENDIF 
RET 


IX = (PTR_TO_S_ON_c}, f.@., IX pts te byte © data area of song for Chx 


@ set for CHr OFF eade 
MSN C get for Chr attenuation 
ASW D set for Cz frequency 


IF area INACTIVE 
tern eff Chix 
CLSE 
CALL UPATWCTRL (send out attenuation) 
CALL UPFREG (eend out frequency? 
Cnr 
RET 


Bee PT_IX_TO_S$aDATa saz 
Bea seng avaber 


ML :© addr of LST_OF_SND_ADDRS 

HL :© ML = 2 

BC :© 6 B SONGNO 

HL :@ HL ¢ BC (i.e , HL mow points to SaDATA‘'S entry in LST_OF_SND_ADDRS) 
€ := (HL), BD -© (HLe2) 

PUSH BE 


POP Ix (3K -© addr byte © Bf this seng's data area) 
RET 


SxDATA 


Deseription: 
nuaber x. 
and the data area used by song nuaber one MUST 
data area storage is allocated according to addresses stored in 


block. 


The song data areas MUST 


Song 


Storage area for the various 


FIGURE pe 


tiesers and output data for song 
in a contiguous block of CPU RAM 
be the first data area in the 


be stored 


LST_OF_SND_ADDRS, aw table stored in CART ROM. 


Byte © of each data area, ina 


indicate two special conditions: 
byte © = OFFH: song(s) using this data area are eis 


ddition to giving CHé and song nueber, can 


byte O = OOH: indicates end of-song data areas 
If SONGNO = 62, the address of a Special sound effect routine is stored in 
bytes 1 and 2. 
Length in bytes: 10 
Location: CPU RAM 
Beginning address: pointed to by a 16 bit entry in LST_OF_SND_ADDRS \ 
i” Contents Hy 
Offset | B7 Bé BS B4 B3 BZ Bi BO } Description 
wr er rn nnn nnn wenn nnn nnn n= B7 - Bé: song channel number, 0 to 3 
0 { CHE | SONGNO ! BS - BO: gong number, 1 to 61 
iat SONGNO = 62, snd effect adr in next 2 bytes 
rn nn en eee usually, the addr of the next note in song; 
1 i the LSB of an address...! 44 SONGNO & OFEH, this is the LSB of the 
Pte mre nnn nn ee ene addr of the special sound.effect routine 
Pern nmr nen nme nn ene usually, the addr of the next note in 60Nng; 
2 i the MSB of an address...! if SONGNO & OFEH, this is the MSB of the 
wr mmr rn nnn nnn ne oe addr of the special sound effect routine 
3 i F2 F3 F4 FS Fé F7 FE FO : bottom & bits of 10 bit freq data 
Perr rrr nnn nnn nen if CHE = 0 (noise): ATN ! © FB SHIFT 
4 tATNICTRL or ATNiO O FO Fi: if CHE = 1 = 3 (tone): MSN = 4 bit ATN, 
Tarr t renner enn nn ncn nn =e LSN = top 2 bits freq (0 © FO Fi) 
wo tr mmm nnn nnn nnn nnn nnn deteraines duration of note: 
5 H NLEN i if freq swept, = @ of steps in the sweep 
FOC if mot, NLEN * 16.7a8 © duration of note 
SES ae H SSeS SSS SSS SeaS freq Sweep duration prescaler: 
6 H Fes H FPSV i FPS = prescaler reload value 
See eK KS SSeS eSSSeSee eee FPSV = teap FPS variable storage 
SERS SSS a= Sere Ket eeoasesec= freq sweep step size: 1 to 127, -1 to -128 
7 H FSTEP i if FSTEP = 0, freq is not to be swept 
Tr rrr nnn nnn nnn nn ee ALEN = @ steps in atnswep: 2 - 15 (0 =) 16) 
8 H ASTEP H ALEN 1 ASTEP = step size: 1 to 7, -1 to -B8 
Tr rn nn ee if whole byte = 00, atn not to be Swept 
wm mete meee nnn nnn nn eee atn duration prescaler: 
9 H APS { APSY { APS = prescaler reload value 
mmr rr mmm mmm nnn mn nnn APSV = temp APS variable storage 
DURATIONS: - 


fixed frequency @& 
frequency Sweep @& 
duration lst step # 
duration all others = 

0 to 15 (0 => 16) 


Fes: 
FPSU: 
NLEN: 


attenuation sweep & 
duration ist step = 
duration all others @& a 
© to 15 


APS: 
APSU: 
ALEN: 


FPS 


0 to 15 (0 => 16) 
0 to 255 (0 => 284) 


(0 => 16) 
© to 15 (0 => 416) 
© to 15 (0 => 16) 


NLEN © 16.7as 
CC(NLEN - 1) & FPS) + initial FPSV) @ 16.7285 


initial FPSU © 16.7es 


C((ALEN = 1) & APS) + initial APSU] & 16.7e5 
initial APSV & 16.7as . 
PS 


Note Hea 
Length in bytes: 


Location: 


: 
Offset { B7 Bé 


0 + CHE } 
or 
0 of eHe 
or 
0 t CHe: 


REST DURATION & 
duration: 1 to 


‘ FIGURE 2 
der 

ai ‘ 

begins each block of 1 to 10 bytes of note data in CART ROM 


Contents i 
BS B4 B3 B2 Bi BO-} Description e 
2% REST 
wen mmr r een enn ne if B7 = 1, header describes a rest: 
1: duration { BY -Bé © channel nusber, 0 - 3 
mmm reer e een e rene B4 - BO = duration, 1 to 30 <— ‘ 


header preceeds mote data or is special indicator: 
Zax NOTE 
mmm meme renner nen = Mote data follows: 
O: Of Of Of type | BT — Bé = channel Muaber, O = 3 
FESR eee Sea ewaSSe Bl - BO = note type, 0 -3, 
&X* END OF SONG / REPEAT SONG 
etd if B4 = 1, end of song on channel in B7-Bé: 
Of 2! Ri 6: 0: O 1 if BZ 1, Fepeat song forever 
Torre mmm enn en nn nn if B3 = 0, don't repeat 
REx SPECIAL EFFECT 
wm tert ete nn this mote is to be “played® by @ Special 


O: OF Of 1! Of O !f SoUNd effect Foutine whose addr is 
Wm mmm nnn n nnn nnn contained in the following 2 bytes 


duration & 16.7as 
31 


FIGURE 3 
LST_OF_SND_ADDRS 


Description: LST_OF_SND_ADDRS is a list of the starting addresses of each 
Song's data area and note list. They are used by JUKE_BOX as source (note 
list! and destination (song data area) pointers. Each song's entries are 

stored as follows: 


Byte 1: LSB of thé address of the start of that Song's note list 
Byte 2: MSB of the address of the start of that song's note list 
Byte 3: LSB of the address of the start of that Song's data area 
Byte 4: MSB of the address of the start of that Song's date area 


The beginning address of LST_OF_SND_ADDRS is stored in a dedicated CPU RAK 16 
bit word, PTR_TO_LST_OF_SND_ADDRS (xxxxH), allowing the cartridge prograseer to 
place LST_OF_SND_ADDRS wherever desired. 


NOTE: In other data structures, six bits are allocated for the Song nusber 
(SONGNO). However, song nusbers 0, 62, and 63 are used as special indicators, 
leaving song nuabers 1 - 61 available. Therefore, the first entry in 
LST_OF_SND_ADDRS is for song number 1. 


Length in bytes: 4 *® total nusber of songs : 
Location: CART ROM 
Beginning address: pointed to by CPU RAM word SLST_OF_SND_ADDRS 
(xxxxH) 
{ Contents i 


Offset { B7 Bé BS B4 BZ B2 Bi BO ! Description 


LLL SOS SO we we we www we www ew ow ww oe we ww wm www we oe we ww eee ee ee 


saa a a of starting adr of the note list for 
0 ! LSB { song 
aera SSSessSs=sases=== -- nuaber 1 


RSS SSSeesesere=Se-sese== of starting adr of the note list for 
i i MSB { song 
SSS Sane tHe sSeesesss<ss== number 1 


So sata lSssssesessasassss<=s of starting adr of the data area for 
2 ‘ LSB { song 
Se ee nuaber 1 


SE SaS cere sess SseseeeaSases= of starting adr of the data area for 
3 H MSB § song 
Smet SeeS SSS SSsesssseaeees fusber 1 


Siler e rar = Sees a<SeSs= of starting adr of the note list for 


4 { LSB $ song 
Serres Sse SSsseesssesS=5 nusber 2 


--------------------------- of starting adr of the data area for 
4Zan Hy ASB 1 song 
wren nn nnn nnn nueber nm (nm = total nusber of songs) 


FIGURE & 
Resta 


Length in bytes: 2 
Location: CART ROM 
Beginning address: pointed to by bytes 182 in that song's data area 


H Contents H 
Offset : B7 Bé BS B4 BI B2 Bi BO} Description i 
a 
a ———nmnmnmememe 4f B? = 1, header describes a rest: 
t) { CHE 11: = duration 1 B4 — BO = duration, 1 to 30 


REST DURATION = duration & 16.7as 
duration: 1 to 30 


Note Type oO: 
Fixed frequency, fixed @ttenuation 


Length in bytes: & . 
Location: CART ROM 
Beginning address: pointed to by bytes 182 in that song's CPU RAM data area 


$ Contents H 
Offset | B7 Bé BS B4 BI BZ Bi BO ! Description 
0 t CHE 1 0: 0: 0: 0: 0: Of header 
i { F2 F3 F4 FS F6 FT FO FO: least Significant & bits of 10 bit frq data 
2 H ATN {0 O© FO FIL! AWe i bit atn data, LSN = top 2 bits freq 


3 i NLEN t NLEN 2 16.785 = duration of note 


NOTE DURATION = NLEN & 16.7as 
NLEN: 1 to 255 (0 =) 256) 


Note 
Swe p 


Length i 
Location 


Type i: 
t frequency, 


mR bytes: é 
: CART ROM 


FIGURE S 


fixed attenuation 


Beginning address: pointed to by bytes 1£2 in that song's CPU RAM data area 


Of fser 


NOTE DUR 

duration 

duration 
FPS: 0 
FPSV: 
NLEN: 


{ Contents 1 
: B7 Bé BS B4 B3 BZ Bi BO } Description 


POSS SO OOS OMS SOC CeCe ee Cee ww ewe wow oo owe 


Oi O: Of 1 & header 


1 
ae 
te et 
ae. en 
ATION @& 


initial FPSV & 16.7es 
FPS 


ist step # 

all others # 

to 15 (0 @> 16) 
0 to 15 (0 => 16) 
0 to 255 (0 => 256) 


1 NLEN © nuaber of steps in the sweep 


freq sweep duration prescaler: 
i FPS = prescaler reload value 
FPSV = initial FPSY 


freq sweep step size: 1 to 127, -1 to -128 


CC(NLEN - 1) & FPS) ¢ initial FPSV) © 16.7e8 


Fi a FIGURE S 
Note Type 2: 
fixed frequency » SwWePt attenuation 


Length in bytes: 6 
Location: CART ROM 
Beginning address: pointed to by bytes 182 in that song's CPU RAM data area 


2 e e 
{ Contents t 
Offset i B7 Bé BS B4 B3 BZ Bi BO ! Description 
0 { CHE { O! Of 0: Of 11 0! header ' 
1 1 F2 F3 F4 FS F6 FT FE FO! least Significant 8 bits of 10 bit frq data 
2 H ATN $+ © O FO Fil ! ATN @ init atn data, LSN = top 2 bits freq 
3 H NLEN | NLEN & 16.7as = duration of note 
a a a ALEN = @ steps in atnswp: 2=- 15 (0 => 16} 
- 4 H ASTEP H ALEN 1 ASTEP = step size: 1 to 7, -1 to -8 
ee ee ae a if whole byte = 00, atn not to be Swept 
Smee a me aa a atn duration prescaler: 
be) : APS { APSY 1 APS = prescaler reload value 
SOR ROR me mm APSV = initial APSY 
NOTE DURATION & NLEN & 16.7es 


NLEN: 1 to 255 (0 =) 256) 


ATN SWEEP DURATION = C(C{ALEN - 1) & APS) 4 initial APSVI B 16.7es 
duration 1st step «= initial APSU 8 16.7a5 
duration all others = APS 

APS: © to 15 (0 @&)> 16) 

APSV: 0 to 15 (0 =) 46) 

ALEN: © to 15 (0 =) 26) 


Note 


Swept frequency, 


Type 3: 


Length in bytes: 8 
CART ROM 
Beginning address: pointed to by bytes 182 in that song's CPU RAM data area 


Location: 


s ‘ a 
H Contents H 
Offset ! B7 Bé BS B4 B3 B2 Bi BO! Description 
0 $ CHE $ Of Of Of Of 11 2 f header ' 
1 : F2 FJ F4 FS F6 FT FB FO } least Sig © bits of init 10 bit frq data 
Zz H ATN ¢ 0 © FO Fi | ATN ® init atn data, LSN © top 2 bits freq 
3 H NLEN i NLEN © nueber of steps in the Sweep 
me me a mee a ee a em freq sweep duration prescaler: 
4 H Fes $ FPSY ‘ FPS @ prescaler reload value 
wer rn mew mn nen mn FPSY = initial FPS 
b) H FSTEP { freq sweep step size: 1 to 127, -1 to -128 
me a a ALEN = @ steps in atnswep: 2- 15 (0 => 16) 
é { ASTEP : ALEN ‘ ASTEP = step size: 1 to 7, -1 to -8 
TTT RR mmm mem mm if whole byte = 00, atn mot to be Swept 
FEE SSL SS SSS SS atn duration prescaler: 
7 H APS H APSY ‘ APS = prescaler reload value 


NOTE DURATION @ 
duration ist step = 
duration all others = 

© to 15 (0 => 16) 


FPS: 
FPSV: 


FPS 


0 to 15 (0 => 16) 


FIGURE T 


Bwept attenuation 


APSV = initial aPsyu 


C((NLEN - 1) & FPS) 4 initial FPSVI & 16.7as 
initial FPSV & 16.7es 


NLEN: 0 to 255 (0 => 256) 


C(CALEN - 1) & APS) ¢ initial APSUI & 16.7es 
initial APSV & 16.7aes 
APS 


ATN SWEEP DURATION e& 

duration 1st Step = 

duration all others = 
APS: 0 te 15 (0 @> 46) 
APSV: O to 15 (0 @) 16) 
ALEN: 0 to 15 (0 @) 36) 


: FIGURE =} 
Noise notes: 
Special case type 2 notes 


Length in bytes: $s 
Location: CART ROM : 
Beginning address: pointed to by bytes 162 in that song's CPU RAM data area 


e o e 
{ Contents t 
Offset | B7 B&é BS B4 B3 B2 Bl BO ! Deseription 


ai eee 


0 {0 ! G6! Of Of OF Of 21 Of header (CHE = 0, indicates noise nore) 
wo ------------------ ~~. MSN © 4 bit noise ATN data (init if swept) 
1 H ATN 1 0 FB SHIFT ! LSN @ noise fontrol data (SHIFT = NFO NFL) 
2 ‘ NLEN $ NLEN & 16.7as = duration Qf note 
ee a a em ALEN = @ steps in atnswp: 2 - 15 (0 =) 16) 
R | i ASTEP { ALEN t ASTEP = step size: 1 to 7, “1 to -8 
a ee ee om if whole byte = 00, atn not to be Swept 
a ae a a atn duration prescaler: 
4 4 APS H APSY 1 APS = prescaler reload value 
em ee APSV = temp APS variable storage 
NOTE DURATION @ NLEN & 16.7a5 


NLEN: 1 to 255 (0 => 286) 


ATN SWEEP DURATION «= CO(ALEN - 1) ® APS) 4 initial APSV] & 16.7as 
duration ist step @ initial APSY & 16.7a5 
duration all others @ APS 

APS: © to 15 (0 => 16) 

APSV: O to 15 (0 =) 16) 

ALEN: © to 15 (0 => 16) 


FIGURE bd 


Dedicated cartridge RAM locations and 
Special Effect format 


Length in bytes: a1 
Location: CPU RAM 
Beginning address: 7020H 


: 


PTR_TO_LST_OF_SND_ADDRS DS 2 spointer to start of LST_OF_SND_ADDRS 


PTR_TO_S_ON_1 DS 2 spointer to data area of song to be Played on CHE 1 
PTR_TO_S ON.2 ps2 . spointer to data area of song to be played on CHE 2 
PTR_TO_S_ON_3 DS 2 spointer to data area of song to be Played on CHé 3 
PTR_TO_S_ON_O DS 2 spointer to data area of song to be Played on CHE 0 
SAVE_CTRL ps1 sLSN = last control data sent to noise generator 


Special Effect format 


All special effect routines should be written in the following forsat 
(SFX = the address of the effect routine, stored in ROM after the effect's 
header, IX is passed pointing to the song's data area): 


SFX: LD (SAVE_x_NNP) HL iSave address of next mote in song 
LD (SAVE_x_SONGNO) ,A save song's SONCNO 
RET zto LOAD_NEXT_NOTE 
SFX+7: LD HL,SAVE_x_SONGNO stest for ist pass through effect 
BIT 7, (HL) 
JR NZ,NOT_PASS 1 
SET 7, (HL) ito prevent further passes thru inits 
ar sinitialize bytes within the data area here 
RET ito LOAD_NEXT_NOTE 
NOT_PASS 1: ... seode for pass 2 or greater starts here, 


swhich algorithsically modifies freq, atn, 
sor control data within song data area 
F spointed to by IX 
RET (to PROCESS _DATA_AREA) if effect not over 
iif here, effect is Over, So restore SONGNO and addr mxt mote in song 
LD HL, (SAVE_x_NNP) sHL := addr next note in song 
LD DE, SAVE_x_SONGNO iDE :@ addr saved song nuaber 
CALL LEAVE_EFFECT itO restore thea to bytes O - 2 in data area 
JP EFXOVER sin PROCESS _DATA_AREA to load Song's next note 
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December 7, 1982 


NOTES AND ERRATA 
for ColecoVision Sound Users' Manual 
Version 1.1 


The following is a list of known errors in the User's Manual and 
of explanatory notes which hopefully serve to clarify some 
of the concepts presented therein. It is suggested that, pricr 
to reading the Manual, corrections be made sccording to the 
following list and references to the explanatory nofes be marked 
at the appropriate passages. 


a set 


page 


page 


page 


page 


page 


FIG 2 


FIG 3 


16 


16 


21 


ae2 ERRATA %e2 


about half way down the page, starting near the right 
margin: 

“where gz = the song's SONCNO" 

- should read = 

delete - There is no necessary relationship between a 
SONGNO and a@ song data area. As becomes clear later, 
several songs (with different SONCNOs) can share the same 
data area. This error also occurs in the first sentence 
of FIGURE 1. 3 


next to last line: 
- add - 
"“O = no sweep" 


first line: 
“PLAYSONCGS" 

- should read - 
“PLAY_SONCGS" 


last two lines: 
WRETs G SET...” 
“RETs C RESET..." 
- should read - 
“RETS <z SET..." 
“RETs Z RESET... 


the following utilities are not generally useful, are not 
available as entry points, and therefore can not be used: 
AREA_SONCG_IS 

UPATNCTRL 

UPFREG 

PT_IX_TO_SxDATA 

UP_CH_DATA_PTRS (on page 22) 


last line of REST description: 
“BG - BO ws duration, i to 31" 
- should read - 

“B4 = BO = duration, 1 to 30" 


about one third down and half way down the page: 
“gaezH" 

- should read -= 

“7020H" 


USER RAM 


This is the area in CRAM that the Cartridge programmer has chosen 
to hold the ten byte song data areas which contain sound and 
timing information to be processed by the OS sound routines. 
These data areas must Be stored as contiguous blocks of ten bytes 


each. In all eases but one, the programmer may choose to “play" 
a gong in any data area; however, song @1 MUST use the FIRST gong 
data area for the OS routines to work Properly. Also, the byte 


immediately following the last byte in the last Gata area MUST be 
Bero (this code tells the OS routine SND_MANAGER to stop looking 
for more song data areas; see bottom of page 5S, Users' Manual). 
This Byte will automatically be set to sero by proper invocation 
of the INIT_SOUND routine before any other OS sound routines are 
called (see pages §S and 13). 

\ 
2) The ColecoVision OS entry point names of some of the sound 
routines and dedicated locations are different from their names 


Given in the Sound Users‘ Manual. They are: 
Entry Point Sound Users' Manual 
PLAY_IT JUKE_BOX 
SOUND_MAN SND_MANACER . 
SOUND_INIT INIT_SOUND 
NOTES PTR_TO_LST_OF_SND_ADDRS 


You should use the entry point names. 


3) Page 22, last paragraph: It is mentioned that a special 
effect routine may want to call the OS sound routines FREQ SWEEP 
and ATN_SWEEP to operate upon data within the effect's data area, 
which “require that data be ordered appropriately within a song 
Gata area". This means: 


Whether or not the special effect uses FREQ_SWEEP or 
ATN_SWEEP: bytes 3 and 4 (see FIGURE 1) MUST contain the 
frequency and attenuation data as specified. This is 
because PLAY_SONGS (called every interrupt) will output 


For FREQ_SWEEP used by itself - in addition to bytes 3 
and 4, bytes S, 6, and 7 must contain data as specified. 
Bytes 8 and 9 may be used for whatever (since FREQ_ SWEEP 
Goesn't look at them). 


For ATN_SWEEP used by itself - in addition to bytes 3 and 
4, bytes 5, 8, and ¥ pust contain data as specified. 
Bytes 6 and 7 may be used for whatever (since ATN_SWEEP 
Goesn't look at them). 


If both FREQ_SWEEP and ATN_SWEEP are used, all bytes in 
the data area must look as specified in FIGURE 1. 


PTR _TO_S_ON_$: 

7026-27H - As above, for tone generator 63. 
PTR_TO_8_ON_0O: 

7028-29H - As above, for tone generator @0 (the noise 
generator). . 


The final Byte at 702AH, SAVE_CTRL, is used by the OS sound 
routines to store data necessary for smooth operation of the 
noise generator (see bottom of page il in the Users * Manual). 
All 11 Bytes should be inittalised before the OS routines which 
operate upon them are called: this is done by calling INIT_SOUND 
and passing the appropriate cartridge-dependent information (see 
Users' Manual pages $ and 13). 

\ 


ROM 


Cartridge ROM to be used by OS sound routines is divided into two 
sections: LST_OF_SND_ADDRS and the Note List. 


LST_OF_SND_ADDRS: 

A contiguous list of @ bytes per each song (or special 
effect) used by the game. In each 4 byte section, the 
first 2 bytes are a pointer to the beginning of the 
song’s note list (also in ROM). The second two bytes are 
a pointer to the song data area in RAM to be used by that 
song (review pages 2 and 3 in the Manual). Of course, 
another song may also use the same data area, since there 
can be (and usually are) more songs than there are data 
areas. NOTE, however, that Song €1 MUST be the first 
entry in LST_OF_SND_ADDRS for the OS routines to operate 
properly. 


-- EXAMPLE -- The first two bytes in this list are a 
pointer to song @i1‘'s note list, as they MUST be. The 
second two bytes are a pointer to the song's data area in 
RAM, shown here pointing to the first song data area as 
also MUST be the case (see later). As can also be seen 
from the figure, the last song happens to use the second 
song data area. 


In summary, there is a note list for every note list 
pointer in LST_OF_SND_ADDRS, but, since songs may share 
RAM data areas, there are almost always more data areas 
than there are data area pointers. 


NOTE LIST: 
The Note List is a contiguous block of ROM containing the data 
which comprise the notes of each song. The number of bytes per 
song of course varies with the length of the song. The first 


byte of the note list for a song is pointed to by a two byte 
entry in LST_OF_SND_ADDRS (see above). The last byte of each 
Song's note list is a single byte end of song/repeat code (see 
page 2 and Figure 2 in the Users' Manual). 


also, half way down the page: 

“...pointed to By CPU RAM word LST_OF_SND_ADDRS" 

- should read - 

“...pointed to by CPU RAM word PTR_TO_LST_OF_SND_ADDRS" 


FIG 4 second line: 
“Length in bytes: 2" 
- should read - 
“Length in bytes: i" 


also, about 6 lines down from that: 
“B4 - BOs duration, 1 toe $i" 

- should read - 

"B4 - BOs duration, 1 to 30" 


wee NOTES 222 


1) After reading through page 6 in the Users' Manual, it may be 
helpful to review the following summary of dedicated pointers and 
data structures (discussion refers to Figure 10, included as part 
of these notes): 


DEDICATED RAM . 


Prior to calling any OS sound routines (except INIT_SOUND), the 
11 CRAM locations 7620H through 702AH must be initialised to 
meaningful data. Ten of the locations are two byte pointers: 


PTR_TO_LST_OF_SND_ADDRS: 

7020-21H - Points to the start of a list of pointers in 
cartridge ROM, LST_OF_SND_ADDRS (see later). The OS 
sound routines know where the cartridge-dependent 
LST_OF_SND_ADDRS is stered through this pointer. It is 
shown pointing to the first byte in this ROM list (as it 
must). 


PTR_TO_S_ON_1: 

7022-23H - This and the following three pointers are used 
by OS sound routines to store the addresses of the four 
gong data areas which currently contain the sound data to 
be modified/output to the four sound generators in the TI 
sound chip. This pointer stores the address for the song 
currently playing on tone generator @1. 


-- EXAMPLE -- PTR_TO_S_ON_3 is shown pointing to the 


second song data area. I.e., data for the song currently 
Playing on tone generator @3 happens to be stored in the 
second song data area. The second data area is used for 


purposes of illustration only: other songs may very well 
require that data for tone generator €3 be stored in @ 
different song data area. ; 


PTR_TO_S_ON_2: 
7024-2S5SH - As above, for tone generator 62. 


APPENDIX D 
DIRECTORY OF COLECOVISION SUFTWARE BULLETINS 


Colecovision Software Bulletin 
Errer in Write_Vram Routine 


i Ml ekwdasede 


O002 Vie eves 


O003...+002+++. OS Bug —- PTR_TO_LST_OF_SND_ADDR in wrong place 
0004.....6..... Technique —- Turning off songs without going into the tables, 
O00S..cceveeses Bug in OS Activete routine e 

O00b..+ee+seeee Release of Additional OS Entry Points 

D007... evevcees Header:uTL 


COGS. cco aee na ey Music Tables 
OOOD.. cv eeveeee SONQGbird File 
O010....+6+6,.646.. Interrupt Handling Routines 


BULLETIN NO. 0001 
May 25, 1982 


TO: DISTRIBUTION ec: Eric Bromely 
Marshall Caras 
FROM: DAVID HWANG Robert Schenck 


SUBJECT: COLECOVISION SOFTWARE BULLETIN 


The Colecovision Software Bulletin has been set up to assist 
Colecovision programming users to understand, maintain and develop 


the system/application software. 
More specifically, its purposes are: \ 


(1) Part of the continuing effort to document the operating system 
Ccurrently OS_7:0S); 


(2) Keep users updated regarding any patches and revisions of the 
operating systen; 


(3) Function as a user’s library for information exchange. Any 
proven routines or modules which can be used as tools to 
facilitate software development will be properly documented here 
with author(s) duly credited. 


BULLETIN NO. 0002 
May 25, 1982 


TO: DISTRIBUTION cc: Eric Bromley 
Marshall Cares 
FROM: Z. SMITH/D. HWANG Robert Schenck 


SUBJECT: ERROR IN WRITE_VRAM ROUTINE 


wwe ewe ew ew ew ew ee oe ee ee ww ww we www ww www www ween eres tere reresess eee eer 


WRITE_VRAM hes a problen: 


It works as advertised for byte counts less than 100H and for byte 
counts thet are even multiples of 100H. For other values, it sub- 
tracts 100H from the actual byte count that is written. 


- Cartridge programmers should deal with this problem (and corresponding 
problems it will cause in any OS routine thet writes VRAM, except for 
WR_SPR_NM_TBL) by always sending numbers of bytes that are less than 
or even multiples of 100H. 


- They should not deal with it by padding their byte counts as this may 
lead to cartridges that fail when the bug is fixed. 


BULLETIN NO. 0003 


June 7, 1982 
e 
TO: DISTRIBUTION cc: Eric Bromley 
Marshall Caras 
FROM: Z. SMITH/D. HWANG Robert Schenck 


SUKJECT: ERROR IN OS SOUND PACKAGE 


ween oe Hem em ee ew we wm = ee ew ww ww a ew nw ee rn wren nr nr een nr ern nn eee eee eee 


There is a bug in the OS sound software: 


- The data structure PTR_TO_LST_OF_SND_ADDR, which takes up 11 RAM 
bytes, is mot located in OS RAM above 73RAH as it should be, but 
instead has been placed in the cartridge programmer’s RAM at 7020H. 
Cartridge programmers should avoid using RAM from 7020H thru 702AH 
when the sound software is in operation. 


BULLETIN NO. 0004 
June 7, 1982 


TO: DISTRIBUTION cc: Eric Bromley 
Marshall Caras 
FROM: Z. SMITH/D. HWANG Robert Schenck 


SURJECT: A TECHNIQUE FOR TURNING OFF SONGS AND SGUNDS 


The need has arisen for a safe way of turning off an individual 
“song” or sound event before its time. The most obvious method, which 
involves writing OFFH to the first byte of that song’s sound area 

is not recommended, since it could lead to incompatibility later on 
if, for any reason, we wanted to change the length of the sound area 
data structure. 


The safest method that I have been able to come up with is to declare 
a “null song" for each sound area which consists of nothing more than 
&@ non-repeating 64’th rest, If this song is allowed to be the highest 
priority song for a given area, playing it will have the effect of 

— turning off whatever sound heppened to be Pleying in that area 
previously. 


BULLETIN NO.- 0005 


6/18/82 
e 
- JO; ~  PISTRIBUTION cc: Eric Bromley 
Marshall Caras 
FROM: Z. Smith/D. HWANG Robert Schenck 
SUBJECT: BUG IN OS ACTIVATE ROUTINE \ 


There is a bug in the OS Activate routine which surfaces when 
Activate is called on a Semi-Mobile object in Graphics Mode 1. 


In this mode, Activate writes the pattern generators for a Semi- 
Mobile object to VRAM properly, but miscalculates the munber and 
placement in VRAM of the corresponding color bytes when operating 
on generators in the upper half of the stable. 


This leads to 2 problems: 
- The upper half of the color table is not written by Activate. 


~ The color bytes intended for this half of the table are 
written elsewhere in VRAM possibly overwriting some other 
table. 


Cartridge programmers should avoid using Activate to write 

pattern generators to VRAM in Graphics Mode 1 whenever possible, 
Or, if it is absolutely necessary to use Activate in this way they 
should count, first of all, on having to write the color table 
separately, and second, on guarding against the second problem 
listed above by isolating the calor table. 


Se a eR eee Sh aay atin: 1s Manan Wane y soee 


? BULLETIN NO. 0006 


™ SEPTEMERER, 17, 1982 


TO: DISTRIBUTION e ec: Eric Bromley 
Marshall Cares 
FROM: K. LAGACE/D. HWANG Robert Schenck 


SURJECT: RELEASE OF ADDITIONAL OS ENTRY POINTS 
OS_SYMBOLS:0S REV. 1 


to by “HL” to LSN ef that 
byte. 


| 
in HL | HL eddr. becomes t 
| MSNIMSN ' : ' 
{ 
{ 


\ 

Hodule Nane lAddress | Description “""7""Inputs.—~S~SC*«dSCsC et pets -""T "Regs. Destroyed | 
wonnnnn-n--- paonamecaiaee-—o-— = ake cneeesnennoes [naan —-—aaenmneioniiemenae———-saaees finweasnesnen————e | 
ADDB16 1 Q01B1H | Adds 8 bit Signed number | - 6 bit @ in A t Altered 16 bit | A,F,B ' 
t i in "A“ to 16 bit number 1 - 16 bit @ addr | @ at HL addr. J H 
! | pointed te by "HL". | in HL t I i 
! ' I ‘ ! ' 
aeeeneneneneieneiael ee ene Seen naam a nere =a aaa eames 
DECLSN { 00190H | Decrements LSN of byte 1 - 6 bit @ addr. | Altered 8 bit JI A,F t 
! t pointed to by “HL" witheutl in HL 1 @ at wl addr. | ' 
! | affecting MSN or "HL". { 1 Z flag if 0 { t 
! ' | 1 C flag if -1. J ! 
ese=sssSe5S= | cee nnn | cee aeenceeemnemeeeneoewes [anenseneeeeeene nnn ae sesateneen lena aeeoen nanan 
DECHMSN 1 00198H ! Decrements MSN eof byte 1-8 bit @ addr. | Altered & bit | A,F ! 
! | pointed to by “HL" without! in HL | @ at HL addr. | ! 
! | affecting LSN or “HL". | 12 fleg if 0 ! 1 
! 4 ' {CC fleg if -1 ' t 
aK SSSesas Jenccenan |aneemcesosamenenanenneeeenn | menses nana sees focennn nanan naees [nownenn mene nnneen | 
“OLSN { OULA6H | Copies MSN of byte pointed! — 8 bit # addr. MSNILSN of @ atl A,F,F t 

! ! ' 

! i ! 

! ' \ 

! { 


ATN_SWEEP 


FREQ_SWEEP 


wee eee meee ene 


EF XOVER 


LEAVE_EFFECT 


oem ce me ce mee eee ee 
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OO2EEH 


Q01DSH 
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FOR SOUND USE ONLY 


Creates attenuation sweeps! See Seund Users 


“by altering attenuation | Manvel 

data stored in song data 1} 

area. U 

eee me ee wm en ww ww eo ew ew we ee eww owe | em nn ee nn nr nn ee ee 
Creates frequency sweeps 1! See Sound Users 


by altering frequency datal Hanual 
stered in gong data area. |} 


See Sound Users 
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BULLETIN NO. @006 
SEPTEMBER 17, 1982 


See Sound Users! 
Manval i 


See Sound Users! 
Manvel 


See Sound Users! 
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See Sound Users! 


BULLETIN NO. 007 
OCTOBER 21, 1982 


TO: DISTRIBUTION cc: Robert Schenck 
FROM: ARD SUFTWARE ENGINEERING 
SUBJECT: HEADER:UTL REV. 3 


Released and Supported on HP64000 systems under USERID:UTL is the 

new revision of HEADER which hes been adopted by Softwere Engineering 
aS part of standard documentation for any module and program developed 
in house (Ref, R. Jepson’s memo July 27, 1982), 


The SETHEAD:UTL has also been updated to Support HEADER Rey, 3 


MEMORANDUMS 


NO. 0008 
OCTOBER 27, 1982 


TO: DISTRIBUTION cc: Robert Schenck 
FROM: MUSIC AND SOUND DEPT./D. HWANG 


SUBJECT: MUSIC TABLES 


LST_OF_SND_ADDRS has formerly been used in all games to denote the 
starting address of a list of pointers to song tables and work 
areas. This label will not be used in the future games. Instead a 
label with postfix "NOTES" will be used. 


For exemple, in the upcoming games: 


DONKEY KONG JR will use KONGIRNOTES 
OMEGA RACE Will use OME GANOTES 
GORF will use GORFNOTES 


MEMORANDUM 


NO. 0009 
OCTOBER 27, 1982 


TQ: DISTRIBUTION cc: Robert Schenck 
FROM: MUSIC AND SOUND DEPT./D. HWANG 


SUBJECT: SONGERIRD FILE 


Effective immediately all work pertaining to music and sounds will 

be done in the SONGRIRD file. To play a song, @ call to a descriptive 
label, which is supplied by the music group, will be used. 

For example: 


CALL BELL_SOUND 


Where BELL_SOUND is a global label in the SONGRIRD file which will 
contain all that is necesary to play that sound or song. This one 
Call approach is replacing the former procedure such as: 


LD 5,3 3 THE SONG NUMBER 
CALL PLAY_IT 
LD B,4 


CALL PLAY_IT 


Within the SONG_BIRD file, song numbers will be EWUAT to descriptive 
labels instead of using absolute numbers. 


BULLETIN NO. 0010 
OCTOBER 27, 1982 


@ 
-7TO0; DISTRIBUTION ec: Eric Bromley 
‘ . Marshall Caras 
FROM: R. JEPSON/D. HWANG Robert Schenck 
\ 


SUFJECT: INTERRUPT HANDLING ROUTINES 


Due to the hardware configuration of ColecoVision, certain routines 
which write to VRAM, such as WRITE-VRAM, could have undetermined 
results if they are interrupted during execution. 


One possible solution to this problem is a defer interrupt routine. 
The function of this routine is to hold off (defer) the servicing 
of the interrupt until the Cartridge program believes it is safe to 
service it, 


An example of a defer interrupt service is attached using @ binary 
semifore type construct. Note that the routines do not stop the 
actual interrupt (they can’t) but just hold off processing the 
interrupt until later. 


The key point to the routine is that another interrupt cannot occur 
until the VDP status register is read. 


An exemple of the use of DEF_INT: 


LD IX ,WRITE_VRAM 31X gets routine that the 
;Ccartridge program does 
snot want interrupted 
CALL OEF_INT . 
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RULLETIN NO. ae 
DECEMBER 22, 198¢ 


TO: DISTRIBUTION ce: Eric Bromley 
“f Robert Schenck 
FROM: ARD SOFTWARE ENGINEERING aw mi r Mershall Cares 
Tom Helmer 


SURJECT: RELEASE OF COLECOVISIDUN PROGRAMMERS 
MANUAL REV. § 


The ColecoVision Programmer’s Manual Rev. S has been released. This 
manual is written for the applicetions Programmer and is intended 

es both a day-to-day reference source as well as a training document 
for programmers new to ColecoVision, 


This new edition contains the overview for both hardware and software, 
Subsequently, detail descriptions are given in the areas of: 


Graphics Generation Software 
Interrupt Handling 
Timing 
Controller Software 
' gund Generation Software 
_-00t up Software and Utilities 
Defined Reference Locations 


The Rev. S&S manual pertains to the current production OS_7. Fundamentel 
knowledge of the OS is presented in the manual without elaborating on 
application examples and design approaches. These materials will be 
documented in the proposed ColecoVision Applications Manual, scheduled 
to be released in second quarter 1983, 


In the Appendix B you will find the graphics documentation (Rev. 1.0) 
has been updated with addition of materials describing PUT_SPRIT and 
PUT_COMPLEX. 


The Sound documentation also received updetes in the form of Notes and 
Errata attached at the end of Appendix C. 


User feedback should be addressed to the Manager of Software Engineering 
of Coleco ARD, All adopted changes will be brought to your attention 
via ColecoVision Bulletin announcements. 


This manual is confidential and should not be copied. All releases 
have to be signed out through the ARD Engineering secretary S, kakowski. 


ce ee ee mm ce ee a we ee ee ee ee ee ee ee 
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ColecoVision Software Bulletin 


BULLETIN NO. 0012 
March 17, 1983 


TO: DISTRIBUTION : B 
FROM: ARD SOFTWARE ENGINEERING ve Wh 


RE: CORRECTIONS IN REGARD TO BULLETIN NO. 0004 


(1) The statement that “Sound Data Areas are off limits to . 
programmers" is not true. 


(2) The "Null Song” method wastes CROM space. Writing OFFH to the 
first byte of the Song's sound area IS recommended. 


Since the ColecoVision Operating System turns off sounds by placing 
OFFH into the first byte of the Sound Data Areas anyway and changing 
the data structures of the Sound Data Areas would entail changing the 
operating system. It has been proven that the above method is the 
fastest and most- direct way to abort sounds. 


The "null song” method may still be used, but each additional song 


uses at least five bytes of CROM; four for the LST_OF_SND_ADDRS 
and one for the END code. 
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ARD Software Engineering QF 


Release of Additional ColecoVision OS Entry Points 


0013 
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The following is a list of additional entry points to the ColecoVision 


OS ROM. 
PX_TO_PTRN_POS 
PUT_FRAME 
GET_BKGRND 


= CALC_OFFSET 


EQU 
EQU 
EQU 


EQU 


O7E8H 
O80BH 
0898H 
O8COH 


Attached is a brief description of the routines which correspond to 
the entry points released. 
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Here are the graphic subroutines which would be useful to 
have access to, along with a brief description of what each one 
does. 


hale eects SS SS SSSSSSSSSSSTSCSSS SSE TESTS SESE TT TT 


@X_TO_PTRN_POS (Pixel to pattern plane position) 
(entry point xxxxH) 


This routine divides the 16 bit Signed value in the DE 
Tegister pair by 6. An & bit signed result is returned in 
Fegister E. Results of less than -127 are returned as -128, 
Fesults of greater than 4126 are returned as +127. 


If this routine is passed the X(or Y) pixel coordinate 
position of a point on the pattern plane, the X(or Y) coordinate 
in pattern positions will be returned. 


INPUT: DE = WN (16 bit signed nusber!} 

OUTPUT: N/8 ¢ -128 —E = -128 
“128 (= N/8 «= 127 E =wn/8 
N/B > €126 E = +127 


REGISTERS AFFECTED: 


FLAGS 
DE 


RARER ATA RAAAA AAA AAAS AAAL ASS AALAAAS AAT SATA AEA AE ARETE TESTE LE 


PUTFRAME 


(entry point xxxxH) CONFIDERT “AL 


PUTFRAME woves data from cpu RAM to the Pattern Nase Table 
in VRAM. The data is assuped to be an array of Pattern Generator 
Nupes which when soved to the Pattern Nase Table, will produce a 
rectangular graphic, or frase, composed of the patterns specified 
by these Pattern Generator Nases. The arecay Bust be arranged in 
fow Bajor order. 


The dimensions of array are passed to the routine in the BC 
Fegister pair. These diwensions also define the height and width 
(in pattern plane positions) of the frase when displayed. 


The upper left eorner ef the frase will appear on the 
Pattern plane at a position detersined by Y_PAT_POS and X_PAT_POS 
which are passed in the DE register pair. Y and X_PAT_POS are 
Fow and eeluen coordinates in pattern plane positions as eseasured 
from the upper left corner of the pattern plane. Y and X_PAT_POS 
are interpreted as @ bit signed values and, therefere, the corner 
of the frame may placed anywhere within or eutside the boundaries 


of the pattern plane. Therefore, the frase itself eay be placed 
partially off screen in any direction. 


The HL register pair aust contain the address of the start 
of the array of pattern nases. 


INPUT: HL © Address of array in CPU RAM 

= Y dimension of array and Y_EXTENT of frase 
= X disension of array and X_EXTENT of frase 
= Y_PAT_POS of upper left eorner of frase 

= X_PAT_POS of upper left corner of frase 


} Shee 


OUTPUT: Modifies VRAM nape table 


Mo Owe 


REGESTERS AFFECTED: 


All registers used 


As an exapple, if an array exists in CPU mesory space which looks 
like... 


ARRAY: DB 0,1,2,3,4,5 


and the first six pattern generators in VRAM have been 
initialized with the following patterns... 


Pattern Generator @ Graphic 
0 a 
1 B 
2 c 
3 D 
& E 
Ss F 


Then the following code sequence... 


LD HL ,@RRAY 


LD B,2 3B :@ Y_EXTENT 
LDC,3 sC :@ X_EXTENT 
LD D,2 sD := Y_PAT_POS 
LD E,-1 ;E :@ X_PAT_POS 


CALL PUT_FRAME 
will produce this display... 


0 X_PAT_POS -> 
Y_PAT_POS hod o. Hie 


CONFIDENT. 


(diagras of upper left corner of pattern plane) 


Mm w 
“am 


4 


Note: Patterns A and D are not seen, Since they would be to the 
left of the left-hand edge of the pattern plane. 


SECLELE KEATS RST SAKE AKL KART KARST ARAEL AAA AA LAA SSAA AISA ES 


CET_BKGRND 
(entry point xxuxxH) 


This routine is the inverse of the PUT_FRAME routine 
described above. CET_BKGRND moves an array of names fros the 
pattern nase table in VRAM into CPU RAM. The dipensions of the 
array and the position of the upper left corner of the frase it 
defines, are passed to the routine in Sane manner as in 
PUT_FRAME. The nmaaes are poved to the location in CPU RAM 
specified by the contents of the HL register pair. 


If part of the frame extends beyond the pattern plane, the 
Mmases that correspond to positions which are not on the pattern 
plane will mot be defined. 


INPUTS: HL = Destination address in CPU RAM to which 
mapes will be aoved 

= Y_EXTENT of frase 

X_EXTENT of frame 

= Y_PAT_POS of upper left corner of frame 

X_PAT_POS of upper left corner of frape 


meow 
L] 


OUTPUTS: CPU RAM from HL to HL+(BSC)-1 filled with nases 
from pattern mame table 


RECISTERS AFFECTED: 
All registers used 
RECA K SAKATA SAKA AKA KATIA AK EAA RAE KAKA RASA KAT AKA AE AAAS 


CALC_OFFSET 
(entry point xxxxH) 


This routine calculates the offset froe the start of the 
pattern name table corresponding to a pattern plane position 
specified by the coordinates Y_PAT_POS and X_PAT_POS. 


The coordinates are passed to, and the result is passed back 
in the DE register pair. 


INPUTS: D = Y_PAT_POS 
E = X_PAT_POS 


OUTPUTS: DE = Offset from start of pattern nase table 


RECISTERS AFFECTED: 
FLacs 
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ColecoVison Software Bulletin 


Bulletin No. 0014 
April 12, 1983 


TO: Distribution ; 
nae! 


FROM: ARD Software Engineering 


ars 


RE: OS_SYMBOLS Rev.4 


Attached please find a listing of OS SYMBOLS Rev. 4. This listing holds al 
ColecoVision OS reserved data entry points released to date. 


Attachment 
Distribution: cCz 
C. Baldyga J. Milano E. Bromley 
R. Dionne M. Minto C. M. Caras 
L. Gray A. Nguyen T. A. Helmer 
C. Hager L. Olbrych D. Hwang 
R. Harris R. Rizzo R. Schenck 
L. Henderson B. Rochette File 
R. Jepson D. Schulze 
D. Jonker D. Stern 
K. Lagace D. Taylor 
J. Michaels D. Thompson 
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APPENDIX E 
, ‘JUMP TABLE 


- PLAY_SOncS 
ACTIVATEP 
PuTOBIP 
REFLECT_VERTICAL 
REFLECT _WORIZONTAL 
ROTATE _96 . 
ENLARGE 
CUNTROLLER_SCAaN 
DECODER 
CAME _OPY 
LOAD_ascrr 
FILL_VRan 
MODE_1 
UP DATE_SP INWER 
IMIT_TADLEP 
CET_VRamp 
PUT_URA@MP 
INIT_SPR_ORDERP 
WR_SPR_wH_TBLP 
INIT_TIMERP 
FREE_SIGNaLP 
REQUEST_SIGNALP 
TEST_SiCwace 
WKITE_REGISTERP 
WRITE _URAMP 
READ_VRaMP 
INIT_BRITERP 
SOUND_INI1TP 
PLAY_ITe 
INIT_TAKLE 
GCET_UR an 
PUT_VRan 
INIT_SPR_ORDER 
SR _SPR_wm_TBL 
INIT_TIMER 
FREE_SIGNAL 
REQUEST _SIGNAL 
TEST_SIGWAL 
TIME _mGR 
TUKW_OFF_SOUND 
WRITE _RECISTER 
READ_RECISTER 
: WRITE_VRAM 
READ_VRaM 
INIT WRITER 
WRITER 
POLLER 
: SOUND_INIT 
7 PLaY_It 
SOUND_MAN 
ACTIVATE 
PuTOBJ 
RAND_CEN 
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APPENDIX F 
OS SYMBOLS ® 


ACTIVATE EQU O1FF7H 


; 0S:0s 
ACTIVATEP EQU 01F64H 3 0S:0S 
ADD816 EQU 001B1H } 0S: 0S 
AMERICA EQU 00069H } oS:0S 
ASCII_TABLE EQU 0006AH } 0S:0S 
ATN_SWEEP EQU 0012FH } os:o0s 
CARTRIDGE EQU 08000H $ 0S: 0S 
CONTROLLER_MAP EQU 08008H 3 0S :0s 
CTRL_PORT_PTR EQU 01D4:3H 
DATA_PORT_PTR EQU 01D47H 
DECLSN EQU 00190H ; os:os 
DECMSN EQU 0019BH } 0S:0S 
DECODER _  EQU 01F79H 3 oS:0S 
DEFER_WRITES EQU 073C6H ~—s oS:os 
EFXOVER EQU 002EEH } 0S:0S 
ENLARGE EQU 01F73H ; os:os 
ENLRG EQU 01D6CH 3 os: 0S 
FILL_URAM EQU 01F82H ; oS:os 
FREE_SIGNAL EQU O1FCAH 3 0S:0S 
FREE_SIGNALP EQU 01F9DH 3 os:os 
FREQ_SWEEP EQU 000FCH 3 oS: 0S 
GAME_NAME EQU 0g024H.-—; 0S:0S 
GAME_OPT EQU 01F7CH ; oS:0S 
GET_URAM EQU 01FREH ; oS :0S 
GET_VRAMP EQU 01F8EH ; os:0s 
INIT_SPR_ORDER EQU 01FC1H } 0S:0S 
INIT_SPR_ORDERP EQU 01F94H } 0S:0S 
INIT_TABLE . EQU 01FB8H ; 0S:0S 
INIT_TABLEP - €EQU 01F8BH ; oS :0S 
INIT_TIMER EQU 01FC7H ; os:os 
INIT_TIMERP -EQU 01F9AH } os: 0S 
INIT_WRITER EQU 01FE5H ; 0S:0S 
INIT_WRITERP EQU 01FAFH } 0S: 0S 
IRQ_INT_VECT EQU 0801EH } OS:oS 
LEAVE_EFFECT EQU 001D5H ; 0S:0S 
LOAD_ASCII ~  EQU O1F7FH } os:0s 
LOCAL_SPR_TBL EQU 08002H ; vS:0S 
MODE_1i EQU 01F85H } 0S:0S 
MSNTOLSN EQU 001A6H ; 0S:0S 
MUX_SPRITES EQU 073C7H ; os:os 
NMI_INT_VECT EQU 08021H ; os:0s 
. NUMBER_TAELE EQU 0006CH } 0S:0S 
PLAY_IT EQU O1FF1H ; 0S: 0S 
- PLAY_ITP EQU O01FESH } oS:0S 
PLAY_SONGS EQU 01F61H 3; 0S:0S 
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POLLER 
PUTOBJ 

PUTOBJP 
PUT_VRAM 
PUT_VRAMP 
RAND_GEN 
RAND_NUM 
READ_REGISTER 
READ_VRAM - 
READ_VRAMP 
REFLECT_HORIZON 
REFLECT_VERTICA 
REQUEST_SIGNAL 
REQUEST_SIGNALP 
ROTATE_90 
RST_10H_RAM 
RST_18H_RAM 
RST_20H_RAM 
RST_28H_RAM 
RST_30H_RAM 
RST_8H_RAM 
SOUND_INIT 
SOUND_INITP 
SOUND_MAN 
SPRITE_ORDER 
STACK 
START_GAME 
TEST_SIGNAL 
TEST_SIGNALP 
TIME_MGR 
TURN_OFF_SOUND 
UP DATE_SPINNER 
VDP _MODE_WORD 
VDP _STATUS_BYTE 
WORK_RUFFER 
WRITER 
WRITE_REGISTER 
WRITE_REGISTERP 
WRITE_VRAM 
WRITE_VRAMP 
WR_SPR_NM_TBL 
WR_SPR_NM_TELP 


EQU 
EQU 


01FEBH 
O1FFAH 
O1F67H 
CiFBEH 
O1F91H 
O1FFDH 
073C8H 
O1FDCH 
O1FE2H 
O1FACH 


O1IF6DH 


01F6AH 
Q1FCDH 
O1FA0H 
01F70H 
OS00FH 
08012H 
08015SH 
08018H 
0801BH 
0800CH 
O1FEEH 
OiFR2H 
O1FF4H 
08004H 
073K9H 


‘O800AH 


O1FDOH 
O1FA3H 
O1FD3H 
O1FD6H 
01F88H 
073C3H 
073CSH 
08006H 
O1FE8H 
O1FD9H 
Oi1FA6H 
O1FDFH 
O1FA9H 
O1FC4H 
O1F97H 
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GLB 
GLB 
GLE 
GLB 
GLR 
GLE 
CLE 
GLR 
GL2 
GLE 
GLB 
GLB 
GLB 
GLB 
GLB 
GLE 
GLB 
GLB 
GLB 
GLE 
GLB 
GLE 
GLB 
GLB 
GLB 
GLR 
CLE 
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GLB 
GLE 
GLB 
GLE 
GLB 
CLB 
GLB 
GLB 
GLE 
GLE 
GLE 
GLB 
GLB 
GLE 
GLB 
CLR 
GLB 
GLR 
GLB 
GLB 
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ACTIVATE 
ACTIVATEP 
ADD816 
AMERICA 
ASCII_TAHLE 
ATN_SWEEP 
CARTRIDGE 
CONTROLLER_MAP 
CTRL_PORT_PTR 
DATA_PORT_PTR 
DECLSN 

DECMSN 
DECODER 
DEFER_WRITES 
EFXOVER 
ENLARGE 

ENLRG 
FILL_URAM 
FREE_SIGNAL 
FREE_SIGNALP 
FREQ_SWEEP 
GAME _NAME 
GAME_OPT 
GET_URAM 
GET_VRAMP 
INIT_SPR_ORDER 
INIT_SPR_ORDERP 
INIT_TABLE 
INIT_TABLEP 
INIT_TIMER 
INIT_TIMERP 
INIT_WRITER 
INIT_WRITERP 
IRQ_INT_VECT 
LEAVE_EFFECT 
LOAD_ASCIT 
LOCAL_SPR_TBL 
MSNTOLSN 
MODE_1 
MUX_SPRITES 
NMI_INT_VECT 
NUMBER_TABLE 
PLAY_IT 
PLAY_ITP 
PLAY_SONGS 
POLLER 

PUTOBJ 
PUTOEJP 
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0S:os 
0s:os 
os:os 
os:os 
OS:os 
0s:os 
os:os 
OSs:os 


os:os 


os;:os 
Oos:os 
Os:os 
OS;:0S 
0S;os 
os:os 
os;:as 
Os:os 
os:os 
Os:os 
os:os 
os:os 
os;:os 
os:os 
Os:os 
0S:oS 
os:os 
0s:os 
os:os 
0S:o0Ss 
o0s;:os 
0S:0O0S 
Oos:os 
0S;:os 
oSs:os 
OS:os 
0s;os 
os:os 
OS:0S 
0s:oS 
0S:0S 
Os:os 
0Ss:os 
O0s:os 
os:os 
os:os 
OS:0S 
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GLB 
GLE 
GLE 
GLE 
CLB 
GLE 
GLB 


GLE 
GLB 
GLE 
GLE 
GLB 
GLR 
GLE 
GLB 
GLE 
GLE 
GLB 
GLR 
GLB 
GLE 
GLB 
GLE 
GLE 
GLR 
GLB 
GLR 
GLB 
GLR 
GLH 
GLE 
GLB 
GLB 
GLB 
GLE 
GLB 
GLE 
GLE 
GLB 


PUT_URAM 
PUT_VRAMP 
RAND_GEN 
RAND_NUM 
READ_REGISTER 
READ_VRAM 
READ_VRAMP 


REFLECT_HORIZON 
REFLECT_VERTICA - 
REQUEST_SIGNAL 
REQUEST ~ =SIGNALP 
ROTATE_90 
RST_10H_RAM 
RST_18H_RAM 
RST_20H_RAM 
RST_28H_RAM 
RST_30H_RAM 
RST_8H_RAM 
SOUND_INIT 
SOUND _INITP 
SOUND _MAN 
SPRITE_ORDER 
STACK 
START_GAME 
TEST_SIGNAL 
TEST_SIGNALP 
TIME_MGR 
TURN_OFF_SOUND 
UP DATE_SPINNER 
VDP _MODE_WORD 
VDP_STATUS_BYTE 
WORK_BUFFER. 
WRITER 
WRITE_REGISTER 
WRITE_REGISTERP 
WRITE_VRAM 
*WRITE_VRAMP 
WR_SPR_NM_TBL 
WR_SPR_NM_TBLP 


0s:os 
OS:oas 
OS;os 
OS:os 
OS;:os 
OS:os 
OS:os 
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OS:os 
0s:os 
Oos:os 
OS:os 
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0S:os 
0S:os 
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0s:os 
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os:os 
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oOS:os 
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OoS:os 
os:os 


pn Pb SY ND to LY ew we we ee ro) rv 
ous ©N wm OCHLCH UTS Ge onrrxiys 


o Oo i DM UO mw Ww 100 wo 


‘ 


COLECOVISION PROGRAMMERS' MANUAL 


Rev. 5 
f ©Coleco Industries, Inc. 1982 
CONFIDENTIAL DOCUMENT - DO NOT Copy Page 1 
APPENDIX G 


TIMING SOFTWARE DATA STRUCTURE 
Table Name: 
TIMER_TABLE 


Description: ' 


A variable length table located in CRAM which 
consists of an array of three byte entries. 
Each entry represents a time request. . 


Access Method: 
Pointed to by TIME_TABLE_BASE. 


Format: 
Each entry appears as: 
7 6 5 4 3 2 1 0 
[LD] Rj FJ E] LT Uy Uy oy 
Where: . 
D: Done 
R: Repeat 
F: Free 
E: Last_Timer_In_Table 
L: Long 
U: Unused 
- a: Counter Byte or pointer to a four byte 


block for long-repeating timers 
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Appendix G (continued) 


Notes: 
Done Bit: This bit is set when the counter has 
finished. 
Repeat Bit: This bit is set to allow TIME_NGR to 
: restart the counter at its original 
value. ‘ 
Free Bit: This bit is set to signify that the 


timer is not in use. 


Last_Timer_In_ Table Bit: This bit indicates the last initialized 
timer in the table. 


Long Bit: This bit defines the timer type. 


QO = Short timer 
1 - Long timer 
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APPENDIX H 
OS SUBROUTINE LIBRARY 


Releases & timer to the free list 
es on SIORAL—wUn 


Roves frequency ané attemation 
Sete to wound ehips 


Reads and returns the eontentes of 
he VDP ister 


